summaryrefslogtreecommitdiff
path: root/systems/doc/metapost
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /systems/doc/metapost
Initial commit
Diffstat (limited to 'systems/doc/metapost')
-rw-r--r--systems/doc/metapost/CHANGES1590
-rw-r--r--systems/doc/metapost/grdemo-doc.pdfbin0 -> 7430 bytes
-rw-r--r--systems/doc/metapost/grdemo.pdfbin0 -> 3044 bytes
-rw-r--r--systems/doc/metapost/mpboxes.pdfbin0 -> 376204 bytes
-rw-r--r--systems/doc/metapost/mpgraph.pdfbin0 -> 472517 bytes
-rw-r--r--systems/doc/metapost/mpintro.pdfbin0 -> 234831 bytes
-rw-r--r--systems/doc/metapost/mplibapi.pdfbin0 -> 280407 bytes
-rw-r--r--systems/doc/metapost/mpman.pdfbin0 -> 957617 bytes
-rw-r--r--systems/doc/metapost/source-manual/Makefile89
-rw-r--r--systems/doc/metapost/source-manual/README21
-rw-r--r--systems/doc/metapost/source-manual/TODO124
-rw-r--r--systems/doc/metapost/source-manual/agepop91.d85
-rw-r--r--systems/doc/metapost/source-manual/agepopm.d85
-rw-r--r--systems/doc/metapost/source-manual/charts.mp120
-rw-r--r--systems/doc/metapost/source-manual/cm2lm.map8
-rw-r--r--systems/doc/metapost/source-manual/countries.d60
-rw-r--r--systems/doc/metapost/source-manual/ctabbing.sty18
-rw-r--r--systems/doc/metapost/source-manual/demo.ms105
-rw-r--r--systems/doc/metapost/source-manual/energy.d75
-rw-r--r--systems/doc/metapost/source-manual/figs.1227
-rw-r--r--systems/doc/metapost/source-manual/figs.mp24
-rw-r--r--systems/doc/metapost/source-manual/grdemo-doc.ms184
-rw-r--r--systems/doc/metapost/source-manual/grdemo-doc.ps1025
-rw-r--r--systems/doc/metapost/source-manual/grdemo.eps779
-rw-r--r--systems/doc/metapost/source-manual/grdemo.mp37
-rw-r--r--systems/doc/metapost/source-manual/grdemo.ms124
-rw-r--r--systems/doc/metapost/source-manual/lead.d24
-rw-r--r--systems/doc/metapost/source-manual/matmul.d21
-rw-r--r--systems/doc/metapost/source-manual/mpboxes.bib19
-rw-r--r--systems/doc/metapost/source-manual/mpboxes.mp146
-rw-r--r--systems/doc/metapost/source-manual/mpboxes.tex572
-rw-r--r--systems/doc/metapost/source-manual/mpgraph.bib98
-rw-r--r--systems/doc/metapost/source-manual/mpgraph.mp141
-rw-r--r--systems/doc/metapost/source-manual/mpgraph.tex1044
-rw-r--r--systems/doc/metapost/source-manual/mplibapi.tex1572
-rw-r--r--systems/doc/metapost/source-manual/mpman-app-legacy.tex347
-rw-r--r--systems/doc/metapost/source-manual/mpman-app-numbersystems.tex98
-rw-r--r--systems/doc/metapost/source-manual/mpman-app-optab.tex156
-rw-r--r--systems/doc/metapost/source-manual/mpman-app-refman.tex1068
-rw-r--r--systems/doc/metapost/source-manual/mpman-charts.mp210
-rw-r--r--systems/doc/metapost/source-manual/mpman.bib135
-rw-r--r--systems/doc/metapost/source-manual/mpman.ist4
-rw-r--r--systems/doc/metapost/source-manual/mpman.mp851
-rw-r--r--systems/doc/metapost/source-manual/mpman.tex6008
-rw-r--r--systems/doc/metapost/source-manual/timepop.d21
-rw-r--r--systems/doc/metapost/source-tutorial/Makefile66
-rw-r--r--systems/doc/metapost/source-tutorial/abstract.tex17
-rw-r--r--systems/doc/metapost/source-tutorial/annulus.mp92
-rw-r--r--systems/doc/metapost/source-tutorial/arrows.tex34
-rw-r--r--systems/doc/metapost/source-tutorial/biblio.tex3
-rw-r--r--systems/doc/metapost/source-tutorial/circles.mp22
-rw-r--r--systems/doc/metapost/source-tutorial/commands.tex13
-rw-r--r--systems/doc/metapost/source-tutorial/compilation.tex56
-rw-r--r--systems/doc/metapost/source-tutorial/conclusion.tex13
-rw-r--r--systems/doc/metapost/source-tutorial/data.d6
-rw-r--r--systems/doc/metapost/source-tutorial/data.mp26
-rw-r--r--systems/doc/metapost/source-tutorial/data.tex159
-rw-r--r--systems/doc/metapost/source-tutorial/draw.mp44
-rw-r--r--systems/doc/metapost/source-tutorial/draw.tex46
-rw-r--r--systems/doc/metapost/source-tutorial/fill.mp22
-rw-r--r--systems/doc/metapost/source-tutorial/fill.tex108
-rw-r--r--systems/doc/metapost/source-tutorial/graph.tex52
-rw-r--r--systems/doc/metapost/source-tutorial/inclusion.tex23
-rw-r--r--systems/doc/metapost/source-tutorial/intro.tex56
-rw-r--r--systems/doc/metapost/source-tutorial/label.mp63
-rw-r--r--systems/doc/metapost/source-tutorial/label.tex99
-rw-r--r--systems/doc/metapost/source-tutorial/mpintro.bib35
-rw-r--r--systems/doc/metapost/source-tutorial/mpintro.ltx182
-rw-r--r--systems/doc/metapost/source-tutorial/paperclip.mp25
-rw-r--r--systems/doc/metapost/source-tutorial/parabola.mp45
-rw-r--r--systems/doc/metapost/source-tutorial/previewer.eps378
-rw-r--r--systems/doc/metapost/source-tutorial/previewer.pdfbin0 -> 20074 bytes
-rw-r--r--systems/doc/metapost/source-tutorial/previewer.pngbin0 -> 16035 bytes
73 files changed, 19000 insertions, 0 deletions
diff --git a/systems/doc/metapost/CHANGES b/systems/doc/metapost/CHANGES
new file mode 100644
index 0000000000..6a36eafb22
--- /dev/null
+++ b/systems/doc/metapost/CHANGES
@@ -0,0 +1,1590 @@
+
+This file is public domain.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.999:
+----------------------------------------------------------------------
+
+* The numbersystem 'binary' is now operational.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.902:
+----------------------------------------------------------------------
+
+* Fixed a crash in 'decimal' mode during choose_scale calculations.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.901:
+----------------------------------------------------------------------
+
+* Fixed a bug in 'decimal' mode that affected (among other things)
+ the directionpoint and bbox calculations.
+
+* Fixed a bug in 'decimal' mode calculation of sine / cosine that
+ affected the precision of the answer in situations where
+ 'numberprecision' was less than 34.
+
+* Updated the number parsing in 'decimal' mode to detect 'too precise'
+ input and optionally generate an error in that case (depends on
+ 'warningcheck')
+
+* Fixed a bug in the svg output where it could crash in 'decimal' mode.
+
+* Fixed a bug in the png output where it could get confused if there
+ was more than one text label
+
+* Fixed a bug in the png output for stroked paths
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.900:
+----------------------------------------------------------------------
+
+* Updated the embedded libraries, and a few build system fixes.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.890:
+----------------------------------------------------------------------
+
+* The numbersystem 'decimal' is now operational.
+
+* New internal: 'numberprecision', for use with 'the 'decimal' number
+ system. The (numeric) value expresses the desired calculation precision,
+ in decimal places.
+
+ system default min max
+ ============================
+ scaled 10 10 10 (assignment effectively ignored)
+ double 16 16 16 (assignment effectively ignored)
+ decimal 34 1 1000
+
+* Bug fix: in the 'double' numbersystem,
+
+ if X = scantokens decimal X:
+
+ will now always be true, because the 'decimal' operator now has
+ the same resolution as the scanning routine (which is two decimal
+ places more than in the previous release).
+
+* Fixed a bug in the handling of the / operator (wrong precendence).
+
+* Fixed a bug in arctime (did not handle negative values currectly).
+
+* Fixed TFM generation issues (various scale-related errors).
+
+* Fixed application crashes when there was no TEXMF tree to be found
+ anywhere.
+
+* It is no longer possible to assign to the 'numbersystem' internal.
+
+* There is a new definition of 'drawdot' in plain.mp.
+
+* PNG output did not output anything for draws of a single point.
+
+* Metapost now prints the full name of any preloaded files.
+
+* Fixed a bug in the handling of labels with embedded ascii zero(es).
+
+* Fixed handling of unknown command-line options, the reporting
+ on used libraries in the --version output, and the banner line.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.803:
+----------------------------------------------------------------------
+
+* Fixed a bug in the path tension handling that sometimes caused
+ distorted output.
+
+* A number of small alterations to the build system making it easier
+ to integrate metapost with W32TEX.
+
+* Fix the internal rounding functions in --numbersystem=double so that
+ they round exactly like in --numbersystem=scaled mode.
+
+* From Elie Roux: a fix to graph.mp to prevent log-scaled graphs with
+ large ranges from causing the "Value is too large" error.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.802:
+----------------------------------------------------------------------
+
+* Fixed a bug causing overly large characters in SVG output mode when
+ prologues != 3.
+
+* Removed a crash during free-ing of TFM metric data at the end of the
+ run.
+
+* Fixed a problem with colors in SVG output mode.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.801:
+----------------------------------------------------------------------
+
+* fixed an off-by-one error in the SVG output that prevented the last
+ font's glyphs from actually being output to the svg file under
+ prologues:=3;
+
+* fixed a bug in bbox calculations in that caused the max y to be set
+ based on the maximum x coordinate internal value instead of the
+ maximum y coordinate.
+
+* fixed a bug where metapost incorrectly produced a 'degenerate spec'
+ error.
+
+* build fixes for various platforms imported from TeXLive 2013, as
+ well as the latest kpathsea development etc.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.800:
+----------------------------------------------------------------------
+
+* A new string valued internal "outputformatoptions" is used by PNG
+ output mode to control the png file format. In the future, this
+ internal may also be used for options to the other output formats.
+
+ The syntax for "outputformatoptions" is a space-separated list of
+ settings. Individual settings are keyword+'='+value. The only
+ currently allowed ones are:
+ format=[rgba|rgb|graya|gray]
+ antialias=[none|fast|good|best]
+ No spaces are allowed on the left, nor on the right, of the equals
+ sign inside a setting.
+
+ The assignment that would match the compiled-in default setup is:
+ outputformatoptions := "format=rgba antialias=fast";
+ however, "outputformatoptions" is initially the empty string.
+
+ Some notes on the (new) PNG output formats:
+ - The 'rgb' and 'gray' subformats have a white background. The
+ 'rgba' and 'graya' subformats have a transparent background.
+ - Bitdepth is always 8.
+ - In all cases, the image is initially created in 8-bit RGB
+ mode. For 'gray' and 'graya', the RGB colors are reduced just
+ before the actual PNG file is written, using a standard rule:
+ g = 0.2126*r + 0.7152*g + 0.0722*b
+ - CMYK colors are always converted to RGB during generation of
+ the output image using:
+ r = 1 - (c+k>1 ? 1 : c+k);
+ g = 1 - (m+k>1 ? 1 : m+k);
+ b = 1 - (y+k>1 ? 1 : y+k);
+ - If you care about color conversions, you should be doing a
+ "within <pic>" loop inside "extra_endfig". The built-in
+ conversions are more of a fallback.
+
+* A new string-valued internal "outputfilename", which is set by
+ "shipout" to the value of the just created file name. Until the
+ first shipout has occurred, it is the empty string.
+
+
+* Fixed a number of bugs where Metapost loaded the default font map
+ file multiple times, resulting in lots of "fontmap entry for
+ `<fontname>' already exists, duplicates ignored" warnings.
+
+* The "glyph <> of <>" operation could crash on fonts with empty
+ subpaths in the charstrings.
+
+* Fixed a bug in the postscript encoding reader that caused a buffer
+ overflow (fatal error) for encoding files that do not end with a
+ newline.
+
+* Sped up png creation a bit by using smarter libpng options.
+
+* In the 'double' numbersystem, lots of precision was lost due to a bad
+ internal conversion of fractions to scaled values. This affected the
+ "rotated by", "directiontime", "sind" and "cosd" primitives, as well
+ as internal dependency calculations.
+
+* In the 'double' numbersystem, an internal rounding error caused
+ "directiontime" to return bad results for requests near zero.
+
+* There was a big scaling miscalculation while outputting glyphs in SVG
+ mode with "prologues:=3". The output labels were so big that they
+ fell completely outside of the generated image.
+
+* A problem resulting in 'This can't happen (endinput)' caused by a
+ missing "end" at the end of the run was fixed.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.790:
+----------------------------------------------------------------------
+
+* Lots of speedups.
+
+* Fixed bug in division expressions that started with a literal number.
+
+* A few problems with bad deallocations were solved.
+
+* A bug where after saving and redefinition of primitives, they later
+ were restored to 'undefined' instead of to their primitive meaning.
+
+* The "double" literal number parser now only accepts scientific
+ notation if the character following 'E' or 'e' is '+', '-', or
+ a digit.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.780:
+----------------------------------------------------------------------
+
+* The turningnumber calculation in 1.770 was bugged.
+
+* The picture export in 1.770 forgot to add trailing zeroes to the
+ log and term output channel resulting in rubbish output.
+
+* The arguments of the PS "dtransform" operator have been fixed
+ (was wrong since 1.750).
+
+* The warning limit in numbersystem=double mode is now exactly 2**52.
+
+* A bunch of obvious memory leaks fixed. Not all yet, but now the
+ MPlib seems to be usable even with many graphics.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.770:
+----------------------------------------------------------------------
+
+This is an alpha release for testing & debugging only!
+
+* The command line switch --numbersystem replaces --math.
+
+* Two new internals: numbersystem (string, read-only, either "scaled"
+ or "double" at the moment) and numberprecision (numeric, currently
+ a no-op).
+
+* There is a new bitmap backend:
+
+ outputformat:="png";
+
+ This backend uses cairo and libpng to generate PNG bitmap data.
+ The created PNG used RGB + Alpha, with anti-aliasing, at 72dpi,
+ and with a transparent background.
+
+* Associated with this, there are new internals "hppp" and "vppp",
+ that are used by the bitmap backend to decide on the scale of
+ the generated bitmap. Default value for both new internals is
+ "1.0", i.e. one pixel per Metapost point.
+
+ The internal names come from metafont.
+
+* There are two new primitives for use with picture item objects:
+
+ prescriptpart
+ postscriptpart
+
+* The C API has been extended to allow path control point resolution
+ without going through the Metapost input language, see
+ manual/mplibapi.tex for details.
+
+* The C API has been extended with a "math_mode" switch in the options
+ structure, and the memory size options as well as "ini_mode" have
+ been removed (the MPlib instance now always starts up in inimp mode)
+
+* The code for picture shipout now uses "double" for all floating point
+ values. This can give small differences in the actual output files in
+ traditional mode due to the required scaled -> double conversion, but
+ was necessary to support the new numerical backend code.
+
+* The Lua API internals have been updated to reflect the C API changes.
+
+* All known crashes in earlier versions of Metapost have been fixed.
+
+Known issues:
+
+* The manual is not up-to-date yet on the metapost input language
+ changes.
+
+* There are various memory leaks.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.750:
+----------------------------------------------------------------------
+
+This is an alpha release for testing & debugging only!
+
+* mpost now accepts --math=double as an argument. This switches the
+ internal arithmetic functions from using a scaled 32-bit data type
+ to 64-bit floating point.
+
+* With --math=double, the input scanner has been changed to allow
+ a := 1.0E20
+ as valid input format for a numerical value
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.504:
+----------------------------------------------------------------------
+
+* Small build system tweaks from TeXLive 2012.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.503:
+----------------------------------------------------------------------
+
+* String comparisons have been fixed, these were broken in previous
+ 1.50x versions.
+
+* verbatimtex ... etex processing had a horrible bug that is now
+ fixed.
+
+* A fix has been applied for a bug that made redeclared variable
+ subscript tags disappear.
+
+* The behavior of the %{<internal>} escape sequence in 'outputtemplate'
+ changed (but not that of the single-letter shortcuts). Internal
+ variables within %{...} are neither rounded nor zero-padded.
+
+* A very long list of improvements to the manual.
+
+* MetaPost now adheres to the openin_any / openout_any settings in
+ texmf.cnf
+
+* The 'prologues:=3 output' with embedded labels was unreliable,
+ especially when the resulting eps was included into a TeX document
+ via dvips.
+
+* 'newinternal numeric' has been fixed, it generated an error in
+ metapost 1.211 and earlier 1.50x versions.
+
+* Label regeneration sometimes failed to run when the file time stamps
+ were close together.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.502:
+----------------------------------------------------------------------
+
+* New build system and kpathsea imported from TeX Live.
+
+* Various bugfixes.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.501:
+----------------------------------------------------------------------
+
+* The maximum number of variable instances has increased from approx.
+ 33 million (2^25-1) to 2 billion (2^31-1).
+
+* New build system and kpathsea imported from TeX Live.
+
+* Many small bugfixes to 1.500.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.500:
+----------------------------------------------------------------------
+
+* Actual memory dump files do not exist any more. --mem=<MEM> and
+ all other methods of supplying a MEM file are now interpreted
+ somewhat like this pseudo-metapost-code:
+
+ begingroup;
+ let dump = end;
+ input MEM[.mp];
+ endgroup;
+
+ this process is supposed to be transparent besides the facto that
+ there is some extra terminal output and logging.
+
+* All memory is now allocated and freed dynamically. There are only
+ two remaining overflow errors(1):
+
+ "expansion depth" : this is a guard against infinite recursion,
+ the value is 10000.
+ "sizes per font" : this is maxed out for data-structure reasons,
+ the value is 32767.
+
+ from texmf.cnf, now only the "error_line", "half_error_line" and
+ "print_line settings" are used.
+
+ (1) but now you can reach the operating system limits, of course.
+
+* As this is an alpha release containing lots and lots of new code,
+ MetaPost starts up with the internal equivalent of 'loggingall;'
+ in effect. This results in log files that can help in debugging.
+
+* Expect bugs and (minor) memory leaks.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.212:
+----------------------------------------------------------------------
+
+* Small build system tweaks from TeXLive 2011.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.211:
+----------------------------------------------------------------------
+
+* In previous 1.20X versions, the 'glyph infont' operator did not handle
+ fonts with seac (old-style composite characters) properly.
+
+* Incorporated the latest versions of kpathsea and the build system
+ from TeXLive.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.210:
+----------------------------------------------------------------------
+
+* In previous 1.20X versions, btex ... etex handling forgot to take
+ the passed directory location of input-ed files into account.
+
+* verbatimtex ... etex is now copied as is. Whitespace stripping
+ and appending of % no longer happen.
+
+* The mpost executable now always strips exactly one extension from
+ the jobname (unless explicit --jobname was given)
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.209:
+----------------------------------------------------------------------
+
+* Previous 1.20X mem files were architecture-dependent.
+
+* Metapost now uses getopt once again, which makes the commandline
+ handling compatible with pre-1.20X versions. However, the syntax
+ -sprologues=1 is now no longer supported (the space between -s
+ prologues is now mandatory).
+
+* On some systems, metapost would crash inside the function that prints
+ the 'fatal error' message.
+
+* The 'glyph infont' operator would sometimes cause crashes, and in
+ other cases it generated bad output.
+
+* There was a space missing in the generated output when mpprocset
+ was set. This was still legal PostScript, but it confused mptopdf.
+
+* In previous 1.20X versions, the font map file was read for each
+ figure that contained a label, resulting in lots of harmless
+ but scary warnings being reported.
+
+* The --debug switch is now documented in the command-line help.
+
+* The help text now mentions the metapost version.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.208:
+----------------------------------------------------------------------
+
+* Previous versions of MetaPost 1.20x were overeager to remove file
+ extensions from the end of the jobname.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.207:
+----------------------------------------------------------------------
+
+* With the -file-line-error commandline option, MetaPost 1.20x always
+ reported the name of the most recently 'input' file instead of the
+ name of the actual current file.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.206:
+----------------------------------------------------------------------
+
+Bug fixes:
+
+* Many of the commands in the MP language cause strings in the string
+ pool to be printed to new strings that are also built up in the
+ string pool. This could cause crashes when the new string wouldn't
+ fit in the memory allocated.
+
+* Failure to initialize the jobname in the MP_options struct could
+ cause crashes in library mode.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.205:
+----------------------------------------------------------------------
+
+Bug fixes:
+
+* Metapost did not handle well files with extensions other than .mp.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.204:
+----------------------------------------------------------------------
+
+Bug fixes:
+
+* Metapost could go into an endless output loop when characters in
+ bitmap fonts where used, because it tried to limit the %*Font output
+ line to a specific number of bytes.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.203:
+----------------------------------------------------------------------
+
+Bug fixes:
+
+* Building version 1.202 for source required X11 headers to be installed.
+
+* Another infinite recursion trap added, now for erroneous vardefs
+ with suffixes (reported by Nicola Vitacolonna).
+
+* Fix infinite loop recursion on integer overflow (reported by Nicola
+ Vitacolonna, fix based on a hint from Dan Luecking).
+
+* In version 1.202, setting "job_name" from lua code caused a crash.
+
+* The "filename" field on the lua figure object in 1.202 was just the
+ extension, instead of the whole file name.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.202:
+----------------------------------------------------------------------
+
+Bug fixes:
+
+* Fix greypart <numeric> (always returned 0).
+
+* Make 'withcolor true' explicitly reset the color model to uninitialized.
+
+* Report which mem file can't be found, and use 'plain' instead of PLAIN
+ in the mem search warning messages.
+
+* Fix a crash on subsetting of some Type1 fonts because of a temporary
+ buffer overrun.
+
+* Correct a crash on SVG text output when the 8th bit is set.
+
+* Fix the use (reference) of 8-bit glyphs in SVG mode when prologues:=3.
+
+* Fix the output of text strings that reference the character at index 0.
+
+* Use ".ps" as file extension for negative charcodes (backward compatility).
+
+* Metapost sometimes printed "mp_vacuous" instead of "vacuous".
+
+* Fix rounding of negative scaled and fraction values.
+
+* Restore the error for 'arctime' out-of-bounds.
+
+* Moved the "turningnumber algorithms do not agree" message out of reach
+ (now only printed if tracingchoices>2 )
+
+* Fix a problem with dash scaling during picture copying.
+
+* TFM header bytes were written out with an offset of one.
+
+* Updated the mptrap files.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.201:
+----------------------------------------------------------------------
+
+Bug fixes:
+
+* There was a bug where sometimes the outer contour of a glyph that was
+ asked for via 'glyph X of' was missing from te output, depending on
+ the path drawing order inside the Type1 font.
+
+* Handling of MPTEXPRE label prefix files was broken.
+
+* Font subsetting for 8-bit characters in Type1 fonts was broken.
+
+* The use of "%{outputtemplate}" inside "outputtemplate" now generates
+ an error.
+
+* The first letter of the input file name was swallowed in the log file.
+
+* There is some rudimentary support for infinite recursion trapping now,
+ to help prevent segfaults&crashes due to C call stack exhaustion.
+
+* An unlucky change in glibc made compilation fail on new GNU/Linux
+ systems due to multiple incompatible definitions of 'getline()'.
+
+* There was a bug in the handling of quoted external commands for
+ MPXCOMMAND | MPXMAINCMD | TEX.
+
+* The main input file's opening brace and filename were not shown in
+ the log file output.
+
+* Non-colored picture objects (clipping and setbounds paths) are now
+ ignored when the color part is asked from within "within", for
+ backward compatibility reasons.
+
+* The trip and trap files are now part of the distribution and the
+ mptrap files have been updated.
+
+* The standard web2c argv[0] mem file mimicri was broken: 1.200 was
+ always looking for "mpost.mem" even when called under another name.
+
+* The manual pages for "mpost" and "dvitomp" have been updated, and the
+ old "mp" manual page has been removed.
+
+* The first letter of any missing input file name was not shown in the
+ terminal error message.
+
+* Output files are now once again written in the current directory even
+ if an explicit source directory is given. This includes the creation
+ of mpx files, but some trickery is used so that up-to-date existing
+ mpx files from the source directory take precedence.
+
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.200:
+----------------------------------------------------------------------
+
+New features:
+
+* It is now possible to get the actual path drawing routines from a
+ font glyph. The syntax is :
+
+ q := glyph 113 of "cmr10";
+ q := glyph "one.oldstyle" of "lmr10";
+
+ "glyph" is a primary binary operator (like "subpath") that accepts
+ a string or number and a string, and the result is a picture.
+
+ The second argument is a tfm name. This will be combined with
+ a fontmap entry to find the font's PostScript source file.
+
+ If the first argument is a string, then it should be a Charstring
+ name in the postscript font source. If the first argument is
+ an integer, it is an index into the encoding of the font, and
+ the Charstring that is mapped to that index is taken (it follows
+ that numeric values have to be integers between 0 and 255).
+
+ The returned picture can be empty (if the tfm or the pfb or the
+ encoding or the Charstring was not found), otherwise it consists
+ of a list of 'fill' objects that use the the 'grey' color model.
+ Counterclockwise paths receive the grey value matching 'white',
+ clockwise paths 'black'.
+
+* MetaPost now supports string valued internal variables. Three of
+ these are predefined ("jobname", "outputformat", "outputtemplate"),
+ you can add more of them via "newinternal".
+
+ newinternal string s;
+ s := "hello";
+
+ The type of a new internal is either 'string' or 'numeric',
+ and defaults to numeric (this is for backward compatibility with
+ older versions of MetaPost). String internals are initialized to
+ the empty string, numeric internals are initialized to zero.
+
+* MetaPost now has a second backend that generates Scalable Vector
+ Graphics output. This new backend was requested by Dave Crossland, who
+ also provided the funding to make it possible. Dave, thank you again!
+
+ The default value of "outputformat" is "eps"; when you assign "svg"
+ you will get SVG output.
+
+ If you use text labels with SVG, you will probably also want to set
+
+ prologues:=3;
+
+ With this setting, MetaPost will convert the font into curves
+ (of course you also need a correct font map line, just as for
+ PostScript output).
+
+ With any other value of "prologues" you will simply get the SVG
+ default text font in a system-dependant encoding. This is unlikely
+ to be what you want!
+
+ A simple example:
+
+ outputformat := "svg";
+ outputtemplate := "%j-%c.svg";
+ beginfig(1);
+ fill fullcircle scaled 100 withcolor .4red;
+ endfig;
+ end.
+
+ In the lua bindings, there is the new figure method "svg()", that
+ gives back the SVG output string. This is subtly different from the
+ direct file output: the lua method does not prepend an XML declaration
+ (this makes embedded use of the generated XML easier).
+
+* The new internal string variable "outputtemplate" replaces
+ "filenametemplate". The big difference is that "outputtemplate"
+ is a true 'internal', so that you need a proper assignment.
+ On the positive side, this means that you can use its current
+ value with e.g. show and message.
+
+* "outputtemplate" has a new type of replacement: internal variable
+ names. Instead of the short "%j.%c", you could write:
+
+ outputtemplate := "%{jobname}.%{charcode}" ;
+
+ this type of replacement works for all internal variables,
+ including those defined via "newinternal".
+
+* There are two new numeric internals: "hour" and "minute".
+ (these are a consequence of the outputtemplate change)
+
+* The primitive "jobname" is now a string internal instead of a
+ special case. This implies you can assign to "jobname", but
+ such an assignment will only affect the picture output. The
+ job name for the purposes of log and mem file names is fixed
+ permanently at startup time and cannot be altered.
+
+* "mpost" can now pretend to be dvitomp. Either copy the executable
+ to the name "dvitomp", or pass the switch --dvitomp on the command
+ line.
+
+* The command line option --halt-on-error has been reinstated.
+
+* There is a new -s<internal>=<value> command line switch that can
+ be used to setup run time values. Such assignment will be executed
+ after initialization is complete (i.e. after mem file loading) but
+ before any other code is executed.
+
+ This works for all internal variables, including one defined
+ that may have been defined in the mem file via "newinternal".
+
+* "tracingstats:=1;" now prints the highest and total input levels.
+
+Bug fixes:
+
+* The turningnumber calculation had a rounding error in the internal
+ arithmetic that could cause incorrect numbers to be calculated
+ (typically resulting in a 'turning numbers do not match' error).
+
+* The parsing of command line arguments with options was broken.
+
+* Reading of files with 8-bit names has been fixed.
+
+* A patch by Melissa O'Neill fixes inclusion of some special Type1
+ formats.
+
+* There was a bug where, when "prologues:=3;", the lists of the
+ DocumentResources/DocumentSuppliedResources could appear in the eps
+ output partially uncommented.
+
+* Troff labels were completely broken in all MPlib-based versions.
+
+Other changes:
+
+* Many, many improvements to the manual and the tutorial. Sorry
+ Stephan, I don't know enough to list them all!
+
+* The old executable build system has been replaced by the new build
+ system from the TeXLive 2009 repository.
+
+* The MetaPost (and mplib) source code is now released under LGPL
+ instead of GPL, and uses a derivative of PyAvl instead of GNU libavl.
+
+* The web2c 'mktexfmt' feature is enabled for the program "mpost" once
+ again.
+
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.102:
+----------------------------------------------------------------------
+
+* Printing of 8-bit string characters has been fixed.
+
+* In previous versions, TFM files and PFB fonts would not be read
+ properly on big-endian machines (e.g. powerpc)
+
+* The MetaPost distribution now contains "A Beginner's Guide to
+ MetaPost for Creating High-Quality Graphics" by Troy Henderson
+ and Stephan Hennig. This tutorial replaces Hobby's mpintro.tex.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.101:
+----------------------------------------------------------------------
+
+This is just a bugfix release. The following bugs / problem areas in
+MetaPost 1.100 have been fixed / improved:
+
+* TFM file generation was completely broken.
+
+* The job name discovery on the commandline has been improved.
+
+* Under some (rare) conditions MetaPost forgot to create a log file.
+
+* Labels containing char0 were exported to PostScript incorrectly.
+
+* On Windows, the DVI file that is the result from the internal call
+ to TeX for btex .. etex lables was not deleted automatically.
+
+----------------------------------------------------------------------
+What is new in MetaPost version 1.100:
+----------------------------------------------------------------------
+
+CHANGES compared to the previous release, 1.005:
+
+* This version is based on MPlib, the C conversion of MetaPost.
+
+ The one user-visible change is that the btex ... etex
+ label conversion is now handled internally instead of via
+ the external "mpware" programs. These programs are therefore
+ no longer distributed.
+
+* There is a new manual, mplibapi.pdf, that describes the internal
+ interface to MPlib.
+
+* The file 'mpintro' is no longer distributed because it is
+ obsolete (it has been that way for some time).
+
+* The distribution now includes Dan Luecking's mpsproof.tex.
+
+
+CHANGES compared to the previous beta, 1.091:
+
+* The DVI -> mpx converter was bugged when virtual fonts were used.
+
+* MP could crash when a string was added to the string pool that
+ was too large to fit.
+
+* The string pool compaction routine was called much too often, thus
+ preventing unnecessary slowdowns.
+
+* Various problems with uninitialized option settings and missing mem
+ files or pfb files have been fixed.
+
+* There was a line buffer overrun possible in the file reader.
+
+* mpost now honours --recorder and --file-line-error.
+
+* MP now accepts file names with paths (separator is /) and with
+ embedded spaces (using " for quoting)
+
+* There could be empty lines in the PS output.
+
+* Full 8-bit fonts (i.e. font using character slot 255) could create
+ an eternal loop.
+
+* The handling of equations with addition or substractions between two
+ unknowns in the right hand side was wrong.
+
+* The first line of the PS font encoding output could be broken
+ inbetween a glyph name and its preceding slash.
+
+* Font inclusion in the PS backend would fail for all fonts that had
+ glyph ids using the 8th bit.
+
+
+----------------------------------------------------------------------
+What is new in MetaPost beta version 1.091:
+----------------------------------------------------------------------
+
+* Dash lists were interfaced incorrectly by the lua bindings.
+
+* The Type 1 Font inclusion in the previous version produced invalid
+ subsets.
+
+* The configure script now also checks for sys/time.h
+
+* The error message you get for invalid mem files now mentions the
+ name of the file as well as the nature of the problem.
+
+----------------------------------------------------------------------
+What is new in MetaPost beta version 1.090:
+----------------------------------------------------------------------
+
+This MetaPost release is based on MPlib. For those of you who are not
+aware of the MPlib project yet:
+
+MPlib is the name of the new, revamped version of the MetaPost
+interpreter. It is implemented in Cweb, and internally consists
+of a core library, an mpx generation library, and a frontend
+driver program (mpost).
+
+There are no changes to the MetaPost language, but nevertheless there
+are some minor differences with the last pascal-web based version of
+MetaPost (1.005):
+
+* The MPlib distribution is released under the GPL version 2 or,
+ at your option, any later version.
+
+* The commandline is slightly different, run mpost --help for details.
+
+* The mem file format is changed, you have to regenerate any
+ existing ones.
+
+* The new mpx generation library includes the label generation
+ functionality that was previously provided by 'makempx', and
+ this internal code will be used instead of an external program.
+ That is, unless the MPXCOMMAND variable is set in the environment
+ or texmf.cnf. The 'mpware' programs became obsolete and are no
+ longer included in the distribution.
+
+* Most of the memory configuration variables from texmf.cnf
+ have become obsolete due to dynamic reallocation. The four remaining
+ ones are 'main_memory', 'hash_size', 'max_in_open', 'param_size'.
+ These are only taken into account at mem generation time, the
+ values are stored in and reloaded from the mem file.
+
+* The core MPlib library does not interpret an initial '&' as anything
+ special and it does not support re-initialization using a different
+ mem file either. The command line program mpost _does_ interpret '&'
+ as an alias for the -mem switch to preserve (some) compatility.
+
+* The MPlib distribution includes lua script language bindings.
+
+Following are the NEWS items for the previous beta releases of MPlib.
+
+----------------------------------------------------------------------
+What is new in the beta release of MPlib 1.090:
+----------------------------------------------------------------------
+
+* The lua bindings to MPlib are added to the distribution, and
+ build.sh can now build an mplib.so loadable module for lua
+ (this needs an installed lua 5.1 distribution)
+
+* Some internal macros are renamed so that the exported C structure
+ fields could have better names, and a new document (mplibapi.tex)
+ provides the documentation of the C api and Lua bindings.
+
+* The texmf and manual trees are now included again.
+
+* (un)dumping mem files is delegated to a separate cweb source file.
+
+* All gcc-isms in the build and configure scripts have been removed.
+
+* The kpathsea library is updated.
+
+----------------------------------------------------------------------
+What is new in the beta release of MPlib 1.085:
+----------------------------------------------------------------------
+
+* Determination of the mem name to use in non-ini mode is now much
+ closer to the web2c approach.
+
+* There is now a magic word in the beginning of the mem file to make
+ sure it is written by the correct version of MPlib.
+
+* Fixed the disappearing comment sign in the to-be-typeset document
+ created by the mpx generation subsystem.
+
+* Various identifiers have been renamed to avoid clashes (that prevented
+ the source from building correctly on many platforms)
+
+* A great many small changes and fixes have been added after running
+ splint on the generated C source.
+
+
+----------------------------------------------------------------------
+What is new in the beta release of MPlib 1.080:
+----------------------------------------------------------------------
+
+* The MPlib distribution is released under the GPL version 2 or, at
+ your option, any later version. The copyright statements in the source
+ files have been updated to reflect this.
+
+* The mpost program banner now contains the kpathsea version, and no
+ longer mentions the fact that the source is now cweb at all.
+
+* The mpost program once again supports 'E' error responses.
+
+* There are some minor internal API changes, but there is still no
+ documentation for the API, so that is not very interesting yet.
+
+
+----------------------------------------------------------------------
+What is new in the beta release of MPlib 1.060:
+----------------------------------------------------------------------
+
+* The MPlib distribution is released under the GPL version 2.
+
+* This release is the first that replaces the old metapost distribution
+ completely. The executable is now named 'mpost' with engine name
+ 'metapost'.
+
+* The release now includes a cweb implementation of the makempx
+ functionality that is linked into the mpost executable.
+ This internal code will be used unless the MPXCOMMAND variable is set.
+ Because of this functionality, the mpware directory is no longer
+ included and the standalone programs 'makempx', 'newer', 'mpto',
+ 'dvitomp' and 'dmp'. are no longer maintained.
+
+* This is the first development release of the new cycle, and contains
+ all of the functionality of Metapost 1.005. The mpost version is now
+ 1.060, and the special version number for the cweb version has been
+ removed from the banner.
+
+----------------------------------------------------------------------
+What is new in the alpha release of MPlib (0.20.0):
+----------------------------------------------------------------------
+
+* Two bugs in MP 1.002 were fixed by Giuseppe Bilotta, both fixes
+ are about polygonals pens and will be included in the upcoming
+ MP 1.003 release also.
+
+* It is now possible to ask for the envelope of a path drawn as
+ traced by a (non-elliptical) pen:
+
+ path p,q;
+ p = fullcircle scaled 30;
+ q = envelope pensquare of p;
+
+* There is a lua interface now, and it is already used by luatex.
+
+ To play with this, currently the best solution is to fetch the
+ 0.25.0 beta of luatex: http://foundry.supelec.fr/projects/luatex
+ This embeds MPlib 0.25.0 as well as its documentation.
+
+* Many bugs were fixed.
+
+----------------------------------------------------------------------
+What is new in the alpha release of MPlib (0.10.0):
+----------------------------------------------------------------------
+
+* The source is converted to cweb, and split into a library part
+ (mpdir/lib/*.w) and a frontend executable (mpdir/mpost.w).
+
+* The front end executable is named "newmpost", this takes
+ care of configuring the MPlib library via C code, and uses
+ kpathsea for file searching. There is no change file involved,
+ and the web2c runtime library is not used.
+
+* Some of the internal arrays now grow dynamically when needed:
+
+ * the input buffer
+ * the string pool and number of strings
+ * the font memory and number of fonts
+ * the number of "readfrom" and "write" files
+ * the path segment size
+ * the input nesting stack
+ * the number of new internals
+ * the TFM writing arrays (but these are limited by TFM format)
+
+ Still not doing that (so these can only be changed in --ini mode):
+
+ * the main memory
+ * the hash size
+ * the number of simultaneous macro parameters
+ * the level of "input" file nesting
+
+* The following command-line options are ignored by the front-end
+ command (for now):
+
+ -[no-]file-line-error
+ -halt-on-error
+ -output-directory=
+ -[no-]parse-first-line
+ -recorder
+ -translate-file=
+ -8bit
+ -T
+
+ The other web2c command-line options should work as normal.
+
+* the mpware tools are not in this distribution, their functionality
+ will eventually be assimilated into the frontend application.
+
+* the build process depends on a local "ctangle" command being in the
+ path, for now. The confiration and building system is not yet complete.
+
+* API documentation is still missing, but the MetaPost input language
+ has not changed.
+
+
+----------------------------------------------------------------------
+What is new in version 1.005:
+----------------------------------------------------------------------
+
+* In MetaPost 1.004, mpost --version still incorrectly reported 1.003
+
+* C Compilation of MetaPost 1.004 was broken on MacOS X 10.5
+
+* The sources package did not contain mpboxes.pdf
+
+* Some last-minute fixes to the manual
+
+
+----------------------------------------------------------------------
+What is new in version 1.004:
+----------------------------------------------------------------------
+
+* The picture color component commands misbehaved in 1.003:
+ the current (default) colormodel was not taken into consideration,
+ so all colors had to be explicit for "redpart" etc. to work.
+ (this bug is the one broke the graph.mp package)
+
+ In 1.004 for "defaulted" colors, the suitable value in the current
+ (default) colormodel is returned without any errors. This change
+ also reverts to silently defaulting a 'black' color when asking
+ for the redpart etc. of an object that cannot be colored at all.
+
+* The picture color component commands misbehaved in 1.003 in
+ a different manner also: the defaults for uninitialized CMYK
+ color picture parts were still assuming 'black' was defined as
+ (1,1,1,1) instead of as (0,0,0,1).
+
+* The macro Gwithpc_ in the graph.mp package did not work properly
+ with non-rgb colormodel objects.
+
+* plain.mp has a new macro, 'colorpart', that returns the color
+ parts of a graphical object within a picture in a form suitable
+ for feeding it back to 'withcolor'.
+
+* The latest kpathsea library from TeXLive is included.
+
+* There is now a separate manual for the boxes package (mpboxes.pdf).
+
+
+----------------------------------------------------------------------
+What is new in version 1.003:
+----------------------------------------------------------------------
+
+* Polygonal pens now work better (bug #3 and #7 at supelec.fr).
+
+* When asking for a color part in a picture object, the color models
+ now have to match each other, otherwise an error will be reported
+ and the return value will be set to a 'black' part.
+
+* The Makefile fragment (metapost.mk) now defines a separate mpost
+ target for better integration in TeXLive.
+
+* There was a bug in the internal handling of withprescript and
+ withpostscript, resulting in incorrect output when paths using
+ such scripts were stored in picture variables.
+
+* A newline was missing from the PostScript output when the
+ procset internal variable was set, so the first line of that
+ accidentally became a PostScript comment.
+
+* Applicable changes from Knuth's updates for MetaFont 2.718281
+ are incorporated.
+
+* Mpto did not play nice with %&<format> verbatimtex lines, it now
+ automatically tries to detect comment-lines.
+
+* Dvitomp 1.003 has higher limits for some internal constants like
+ the number of allowed fonts in DVI files.
+
+* The manual is improved.
+
+
+
+----------------------------------------------------------------------
+What is new in version 1.002:
+----------------------------------------------------------------------
+
+* Version 1.001 introduced a memory allocation error in mpto that could
+ result in the program looping endlessly
+
+----------------------------------------------------------------------
+What is new in version 1.001:
+----------------------------------------------------------------------
+
+* The default cmyk 'black' color now uses only black, not all four
+ ink colors (after a discussion on the mailing list).
+
+* Some issues were reported with the new turningnumber algorithm,
+ all known problems are now fixed.
+
+* Gábor Braun discovered that mpost did not always download the font
+ encodings into all the created output files.
+
+* Akira Kakuto and Hartmut Henkel found some small issues in mpto
+ regarding trailing and leading whitespace.
+
+* A fix for the 'Helvetica' entries in trfonts.map was provided by
+ Werner Lemberg, and Michail Vidiassov supplied two extra font
+ entries for troff.map (Symbol and ZapfDingbats). Karl Berry
+ provided the new file troff-updmap.map, to be used by the updmap
+ tool in texlive.
+
+* Mpost now supports web2c's --output-directory option.
+
+* Any warnings about missing fonts and characters are now always
+ written to the terminal as well as to the log.
+
+* Now that makempx is a C program, it needed a different install line
+ in build.sh. Also, Olaf Mersmann contributed a patch to recognize
+ 'gmake' in build.sh
+
+* Luigi Scarso found some typing errors in the web source that prevented
+ clean weaving of the source.
+
+* Stephan Hennig fixed a number of problems in the manual (mpman.tex)
+ and the introduction paper (mpintro.tex). He also wrote new sections on
+ how to preview metapost graphics and on how to use metapost graphics
+ inside other documents. On top of that, the manual is now hypertext-aware,
+ and fixes for a whole series of small problems have been applied.
+
+----------------------------------------------------------------------
+What is new in version 1.000:
+----------------------------------------------------------------------
+
+* The use of DSC (document structuring) comments has been
+ been cleaned up, thanks to comments by Michail Vidiassov.
+
+* By setting prologues to 2 or 3, you can ask MetaPost to
+ reencode and include the used labels fonts in the output,
+ thus creating proper Encapsulated PostScript files even
+ if labels are present.
+
+* Support for greyscale and cmykcolor models is added.
+
+* The new drawing options "withprescript" and withpostscript"
+ allow the user to attach PostSCript special text to a specific
+ drawing object.
+
+* Setting the new internal "mpprocset" to 1 will make MetaPost
+ create a somewhat extended preamble that defines shortcuts
+ for the postscript commands (e..g "l" instead of "lineto").
+ For big images, this can help shrink the output a bit.
+
+* The pool file is now integrated in the executable, so there
+ is not separate 'mp.pool' anymore, except at build time.
+
+* Groff support is redone, and dmp now uses kpathsea searching.
+ Groff related changes are thanks to the efforts of Werner
+ Lemberg and Michail Vidiassov
+
+* makempx is now a compiled executable on all systems,
+ thank you Akira Kakuto
+
+* The error for 'special's longer then 255 characters
+ is removed, so specials can now be of any length.
+
+* There is new turningnumber implementation that attempts
+ to find the mathematically correct "turningnumber" of a
+ path. The formulae are derived from a mailinglist discussion
+ between (especially) Dan Luecking and Giuseppe Bilotta.
+
+* The manual is updated and modernized. It is currently
+ maintained by Stephan Hennig and Troy Henderson.
+
+------------------------------------------------------------------
+Changes in version 0.920:
+----------------------------------------------------------------------
+
+* Fixed a long-standing bug in web2c where changing values of the
+ memory_size setting in web2c could cause crashes and other random
+ problems. The memory array size is now written to the dump file
+ and loading is aborted if the values do not match.
+* Implement configurable figure output filename templates.
+* Implement cmyk, greyscale, and marking only color models.
+* The mpost executable is now version 0.920
+* mpost no longer autoconverts r==g==b colors to grayscale in the
+ postscript output.
+
+----------------------------------------------------------------------
+Changes in version 0.902:
+----------------------------------------------------------------------
+* Fix a bug in mpto resulting in correctly placed labels (with
+ thanks to Dan Luecking)
+* Fix a bug blocking compilation of dmp on MacOSX
+* The mpost,dmp,mpto executables are now version 0.902
+
+
+----------------------------------------------------------------------
+Changes in version 0.901:
+----------------------------------------------------------------------
+* A corrected bugfix for bug item 3 from version 0.9 (the old fix
+ made metapost fail the trap test)
+* Included mpost.mp for mem generation
+* Updated the trap test output.
+* The mpost executable is now version 0.901
+
+----------------------------------------------------------------------
+What is new in version 0.9:
+----------------------------------------------------------------------
+1. There is a new internal quantity called mpversion that reports the
+ current metapost version, and the version information is also written
+ to the PostScript file.
+2. The LaTeX sources of the mpman, mpintro, and mpgraph manuals have
+ become part of the distribution package.
+3. TEX.mp now has TeX format support through a pair of macros called
+ TEXPRE() and TEXPOST(). This llows you to process the contents of
+ the TEX() macro with, for example, LaTeX (instead of plain TeX).
+ An example is given in the manual.
+4. metapost now writes a %%HiReSBoundingBox comment
+5. The EPS output no longer contains actual spaces within PostScript
+ strings as for example output by label("a space"), but their
+ octal escape (\040) instead.
+6. The EPS output now also has a %%BeginProlog DSC comment
+ as well as %%EndProlog
+7. The comments in the Web source have been changed to point out
+ that on modern machines, acquiring the random seed has actually
+ become a system-dependant operation (a granularity of whole seconds
+ is not small enough on new machines).
+8. The 'newer' command now accepts more than 2 arguments, testing
+ each of the files in turn.
+
+----------------------------------------------------------------------
+Bugfixes in version 0.9:
+----------------------------------------------------------------------
+1. Documentation improvements: all known errata and typos have been
+ removed, better explanations of e.g. dash patterns and dotlabel have
+ been provided, and a number of omissions has been rectified.
+2. The BoundingBox was not computed correctly when a filldraw command
+ with a noticeable pen size was used at the edge of the picture.
+3. Paths starting with degenerate constructions like (0,0)--(0,0)--(0,0)
+ could overflow memory.
+4. The PostScript output could accidentally contain 8-bit characters
+ within PostScript strings in previous versions because a test was
+ shared between terminal printing and PostScript printing.
+5. A bug has been found in the assignment of serial numbers to independant
+ variables in metafont 2.71828. This bug affected MP as well, and the
+ same patch has been applied.
+6. The turningnumber was sometimes wrong in unexpected ways. The new
+ implementation is still sometimes wrong (when there are strange path
+ segments involved), but in a much more predictable way: the new code
+ always draws straight lines between the actual points, and calculates
+ the turningnumber based on that path instead of the actual path. The
+ effect is that cusps and loops within segments are now completely
+ ignored. A more thorough fix of turningnumber is planned for the
+ next release.
+7. There was an 'off by one' error in dvitomp wrt. the interpretation
+ of virtual fonts.
+8. mpto uses a new TeX macro for the generation of labels, making it
+ more robust wrt. strange user code within the actual label text.
+9. A missing colon in boxes.mp has been added
+10. A missing save in mfplain.mp has been added
+11. The generisize in boxes.mp has been fixed so that it now accepts [[ as
+ a valid variable name
+
+----------------------------------------------------------------------
+Version 0.641:
+----------------------------------------------------------------------
+The only change was to fix the code for transforming a picture that
+contains a filldraw. Version 0.64 introduced a bug that caused an
+inappropriate memory reference in that case.
+
+----------------------------------------------------------------------
+What is new in Version 0.64:
+----------------------------------------------------------------------
+1. A new primitive command closefrom filename closes a readfrom file
+ so that subsequent calls to readfrom with that file name will go back
+ to the beginning of the file.
+2. The ^^ notation for unprintable characters is now used only when printing
+ on the terminal or the log file. Internal computations and the write
+ command are all 8-bit clean. (This is partly due to material in mp.ch
+ that changes the initialization of the xchr array. Without these
+ system-dependent changes, the write command would map all non-ascii
+ characters to spaces.)
+3. Arithmetic overflow during a comparison such as 20000>-20000 is now
+ ignored. This avoids extraneous error message when using the graph.mp
+ macro package.
+4. Transformations with negative determinants now work properly on pictures
+ drawn with polygonal pens.
+5. When the readfrom operator is applied to a file that does not exist,
+ an attempt to close a non-open file could cause problems in some
+ implementations. This has now been fixed.
+6. Using draw picture_expression withpen where the picture_expression
+ was a scaled picture containing dashed lines, the dash lengths would
+ change. This bug has been fixed.
+7. The dashpart operator could return an invalid picture or a picture that
+ is not properly scaled. This has also been fixed.
+8. The |char_base| variable could become negative when using fonts that
+ do not start at character 0. There was also bad Pascal code in function
+ b_open_in. This has all been fixed.
+9. Dvitomp has been fixed to avoid a font data structure problem that
+ could cause some characters to come out in the wrong font when you
+ mix virtual and non-virtual fonts.
+10. Dvitomp now correctly prints font names when there is a checksum
+ mismatch, and it aborts instead of just printing an error if a tfm
+ or vf file is bad.
+11. In plain.mp, the drawdblarrow macro now uses filldraw so that it works
+ better with large pen sizes.
+
+----------------------------------------------------------------------
+Version 0.632:
+----------------------------------------------------------------------
+When prologues is negative, the output files use full precision for
+coordinates in "%%BoundingBox" comments. In btex..etex blocks,
+"number too large" and "invalid character" errors are suppressed.
+The result of btex..etex is now guaranteed to be in a setbounds path
+so that a for...within iteration will always treat it as a unit.
+
+There are also some obscure bug fixes involving string compaction when
+scanning a file name or when mp is compiled in debug mode. Some possible
+identifier name conflicts and range check errors have also been fixed.
+
+
+----------------------------------------------------------------------
+Version 0.631:
+----------------------------------------------------------------------
+This version fixes an obscure bug that could cause certain perfectly valid
+strings to be printed as "???" or " NONEXISTENT". It also includes a minor
+fix to the PATHEXPAND code that prevents running out of file descriptors.
+
+
+----------------------------------------------------------------------
+What is new in Version 0.63:
+----------------------------------------------------------------------
+1. Backslashes in the PostScript output are rendered correctly. They used
+ to come out as (\) instead of (\\).
+2. Recycling an independent variable should no longer cause spurious overflows.
+ (This bug was recently found in mf.web.)
+3. Pythagorean addition should now be faster in certain trivial cases.
+4. Rotating text by arbitrary angles should no longer cause bad PostScript
+ output. The problem was that arguments to "fshow" could be inaccurate.
+5. Obscure bugs inherited from mf.web are now fixed. These involve
+ balancing parentheses showing on the terminal, reporting the correct
+ line number in case of buffer overflow, and removing spurious reference
+ counts that could effect end-of-job statistics.
+6. Fonts with ec=255 should no longer cause mp's PostScript output routines
+ to go into a loop.
+7. When mp's string mechanism was heavily used, file names could occaisonally
+ be printed on the terminal and log file as "(?)". This has been fixed.
+8. Setting PATHEXPAND in site.h causes mp, dvitomp and dmp to understand "//"
+ in path variables as "search multiple levels of subdirectories". This is
+ for compatibility with recent versions of the Web2c TeX distribution.
+9. A typo in mpware/makempx and mpware/troffmpx has been fixed. Previous
+ versions of these scripts would not run on some systems.
+10. Data files *.d have been added to the doc directory. These are used by
+ doc/mpgraph.mp which generates figures for "Drawing Graphs with MetaPost".
+11. Typos in mpintro.tex and mp.web's TeX material have been fixed.
+12. Files examples.mp, mpintro.tex and mpintro.bib have moved from mplib to
+ the doc directory.
+13. The author's email address now appears in the README file.
+
+
+----------------------------------------------------------------------
+Macros added to the mplib directory between Versions 0.50 and 0.62:
+----------------------------------------------------------------------
+rboxes.mp is a slightly more general version of boxes.mp
+TEX.mp provides a way of running tex dynamically instead of as a pre-processor
+graph.mp, format.mp, and sarith.mp are documented in doc/mpgraph.ps
+(This is the same as ftp://netlib.att.com/netlib/att/cs/cstr/164.ps.Z)
+marith.mp, string.mp, texnum.mp, and troffnum.mp are low-level packages
+used by graph.mp, format.mp, and sarith.mp.
+
+
+----------------------------------------------------------------------
+Other minor bug fixes subsequent to Version 0.60
+----------------------------------------------------------------------
+1. plain.mp has been fixed so that the x**y works properly when x<0 and y is
+ a negative integer.
+2. Programs mptotex.c and mptotr.c which extract btex..etex material have been
+ fixed so they work properly with input files that do not end with a newline
+ character.
+3. Program dmp.c which handles troff output from btex..etex blocks has been
+ modified to avoid outputting any non-ASCII characters that the C function
+ isprint() accepts.
+4. Program dmp.c no longer gets troff graphics specials confused with text.
+ This seldom matters because btex..etex blocks are unlikely to contain
+ troff graphics.
+5. Pictures containing clipped subpictures could come out with some colors
+ in the subpicture wrong.
+6. Colors in PostSript output were not being restricted to the standard 0..1
+ range.
+7. Transforming a path or a pen should no longer generate extraneous overflow
+ errors in certain unusual situations.
+8. Drawing with a degenerate 2-vertex polygonal pen such as penrazor should
+ no longer cause an infinite loop in certain unusual situations.
+9. There were some bugs in the mfplain macros. (These macros are designed
+ to similate plain METAFONT.) The drawing and filling macros now apply
+ currenttransform to the path but not the pen rather than vice versa.
+ The predefined modes now set o_correction to 1.0.
+10. For security reasons, mp can no longer read or write files whose names
+ begin with '.'
+
+
+----------------------------------------------------------------------
+Changes to the MetaPost language between Version 0.50 and Version 0.60
+----------------------------------------------------------------------
+1. New operator `readfrom <filename>' and new command
+ `write <string expression> to <filename>' do file I/O. Plain defines
+ a special string EOF that readfrom returns to indicate end-of-file
+ and write..to understands as well.
+2. New iteration type `for p within <picture expression>: <loop text> endfor'
+ iterates through the interior components of the picture. An `interior
+ component' is a single pen stroke, filled outline, or piece of typeset
+ text. A part of the picture enclosed in a clipping or setbounds path
+ also counts as an interior component. If the whole picture is enclosed
+ in such a path, the for..within iteration looks inside. Note that a
+ picture generated by btex..etex is enclosed in a setbounds path.
+3. The length operator now applies to pictures. It returns the number of
+ interior components.
+4. New boolean operators stroked, filled, textual, clipped, bounded test
+ the first component of a picture. A picture enclosed in a clipping or
+ setbounds path counts as a single component.
+5. Part extraction operators now work for pictures. Standard operators
+ redpart, greenpart, bluepart apply to the color of the first component
+ and xpart, ypart, xxpart, xypart, yxpart, yypart extract parts of the
+ tranformation that has been applied to a text component. If `textual p'
+ is false, the transform components are all zero; if `clipped p' or
+ `bounded p' is true, the color parts are all zero. Additional operators
+ fontpart, textpart, pathpart, penpart, dashpart extract other information
+ from the first component of a picture. They all return null values when
+ the first component has the wrong type: fontpart and textpart return
+ null strings; pathpart returns the path (0,0); penpart returns nullpen;
+ and dashpart returns nullpicture.
+6. The construction `dashed nullpicture' is now a no-op. It used to be
+ an error.
+7. The clip and setbounds statements used to ignore operations on empty
+ pictures. Now they do not.
+8. Structuring comments in the PostScript output are now based on EPSF-3.0
+ as described in the 2nd Edition of the PostScript Reference Manual.
+ When prologues is 0, some structuring comments are included but the
+ output is not flagged a `conforming document'. Previous versions of
+ MetaPost behaved similarly but used slightly different structuring
+ comments.
+9. When warningcheck is 0, numeric tokens and results from the hex and
+ oct operators can be as large as 32767.99998. The old limit of about
+ 4096 applies only when warningcheck is positive.
+10. Various optimizations should make the output a little more compact.
+11. For PostScript engines that obey the scan-conversion rules documented
+ in the 2nd edition PostScript Language Reference Manual, hrules and
+ vrules in btex..etex blocks should now come out to exactly the right
+ number of pixels. The change affects all pen strokes drawn in MetaPost
+ It is implemented via PostScripts dtransform and idtransform operators.
+12. A bug involving setbounds and MetaPost's corner operators has been fixed.
+13. Degenerate elliptical pens no longer cause PostScript to divide by zero.
+14. Fixed a very obscure bug involving readstring and end-of-file.
+15. String compaction statistics are now printed correctly when the job
+ terminates with tracingstats positive.
+
+
+
+----------------------------------------------------------------------
+Changes to the source files between Version 0.50 and Version 0.60
+----------------------------------------------------------------------
+
+CHANGES to ./README.MP
+The installation instructions should now be clearer. They also explain
+how to cope with verious versions of WEB2C.
+
+CHANGES to ./site.h
+I removed unused entries and clarified instructions in commentary material.
+Confusing comments about possibly merging it with the WEB2C version of site.h
+were removed--I think such merging is a bad idea.
+
+CHANGES TO ./Makefile, mp/Makefile, mpware/Makefile:
+Improved default settings, simplified the `install' recipe,
+fixed a few missing depencies, portability problems, etc.
+
+RENAMED FILES
+ mp/mp.defines, mpware/mpware.defines, mpware/dvitompext.c
+TO mp/mp.def, mpware/mpware.def, mpware/dvimpext.c
+(The names also changed in the Makefiles and convert scripts)
+
+CHANGES TO mp/mp.web, mp/mp.ch, mp/mp.def, mp/mpext.c:
+Lots of new features were added as noted above. The only new system-
+dependencies are for `readfrom' and `write...to'.
+The change file now increases max_read_files; it doesn't bother with
+max_write_files, but perhaps it should. There is a new change entitled
+"Path selector for..readfrom file". From the web2C sources I borrowed
+a change "`logname' is declared in <unistd.h> in some systems". I also
+added a PASCAL-like eof() routine to mpext, removed a change entitled
+"avoid using eof() in read_psname_table" and added a new change
+"[48.1199] `eof'...[in read_mem_file]".
+
+Reorganization of math routines in the mp directory:
+I moved the floating-point math routines from mpext.c to mpath.c. A
+C-language version of the standard math routines was moved from mpmath.c
+to a new file pmath.c for use in mathtest only. This required chages to
+mathtest.c and time.c (also used only for mathtest). The point of all
+this is that there is now just one copy of the floating-point math routines
+and it is used for mathtest and (optionally) for mp itself.
+
+Routines in doc and mp/trapdir:
+The output was updated to Version 0.60. Another test file mptrap.mp
+tests new features. There have also been minor updates to the manual,
+although the new features for Version 0.60 are not included yet.
+
+CHANGES to macros in mplib:
+A minor change to boxes.mp should make it more robust. Changed default
+setting of tracinglostchars in mfplain.mp and plain.mp. Added a string
+constant EOF to plain.mp for use with readfrom and write..to.
+Changed mproof.tex to make it more portable as suggested by Knuth.
+
+CHANGES to mpware/dvitomp.web, mpware/dvitomp.ch:
+The web file was changed to output rules as horizontal or vertical
+penstrokes with butt endcaps. This also affected dvitomp.ch. Also in
+dvitomp.ch, put terminal output on stdout instead of stderr and require
+the output file to be given on the command line.
+
+CHANGES to mpware/makempx, mpware/troffmpx:
+Added comments explaining what path names need fixing. Portability improvements
+and dvitomp's output change affect makempx only.
+
+CHANGES to mpware/mptotex.c mpware/mptotr.c mpware/testex.err mpware/testex.mp:
+Ignore an initial newline in the TeX (or troff) material to avoid generating
+a blank line in the output file. The test file now covers this case.
+
+CHANGE to mpware/newer.c
+Minor changes to make it compile in strict ANSI/POSIX environments.
diff --git a/systems/doc/metapost/grdemo-doc.pdf b/systems/doc/metapost/grdemo-doc.pdf
new file mode 100644
index 0000000000..4d11331f52
--- /dev/null
+++ b/systems/doc/metapost/grdemo-doc.pdf
Binary files differ
diff --git a/systems/doc/metapost/grdemo.pdf b/systems/doc/metapost/grdemo.pdf
new file mode 100644
index 0000000000..faeaa99e6f
--- /dev/null
+++ b/systems/doc/metapost/grdemo.pdf
Binary files differ
diff --git a/systems/doc/metapost/mpboxes.pdf b/systems/doc/metapost/mpboxes.pdf
new file mode 100644
index 0000000000..dba64f0c39
--- /dev/null
+++ b/systems/doc/metapost/mpboxes.pdf
Binary files differ
diff --git a/systems/doc/metapost/mpgraph.pdf b/systems/doc/metapost/mpgraph.pdf
new file mode 100644
index 0000000000..2ec2ac7801
--- /dev/null
+++ b/systems/doc/metapost/mpgraph.pdf
Binary files differ
diff --git a/systems/doc/metapost/mpintro.pdf b/systems/doc/metapost/mpintro.pdf
new file mode 100644
index 0000000000..29b6d37175
--- /dev/null
+++ b/systems/doc/metapost/mpintro.pdf
Binary files differ
diff --git a/systems/doc/metapost/mplibapi.pdf b/systems/doc/metapost/mplibapi.pdf
new file mode 100644
index 0000000000..de3847e0e5
--- /dev/null
+++ b/systems/doc/metapost/mplibapi.pdf
Binary files differ
diff --git a/systems/doc/metapost/mpman.pdf b/systems/doc/metapost/mpman.pdf
new file mode 100644
index 0000000000..16e32d2ca4
--- /dev/null
+++ b/systems/doc/metapost/mpman.pdf
Binary files differ
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 <pic> withpen" and
+ "label(<pic>, ...) 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 &center point &\\
+n &top center point &\\
+s &bottom center point &\\
+w &center left point &\\
+e &center 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 <picture>
+
+In addition to the standard drawing options, the \tdescr{option list} in a
+{\tt gdraw} statement can contain
+$$ {\tt plot}\ \descr{picture expression} $$
+The \tdescr{picture expression} gives a plotting symbol to be drawn at each
+path knot. The {\tt plot} option suppresses line drawing so that%
+\footnote{Troff users should replace {\tt btex \$\string\bullet\$ etex} with
+{\tt btex \string\(bu etex}.}
+\Ignore{\)}% Help delatex so spell will work
+$$ \hbox{\verb|gdraw "agepop91.d" plot btex $\bullet$ etex|} $$
+generates only bullets as shown in Figure~\ref{fig2}.
+(Following the {\tt plot} option with a {\tt withpen} option would
+cause the line to reappear superimposed on the plotting symbols.)
+
+\begin{figure}[htp]
+$$ \includegraphics{mpgraph-2.mps} $$
+\caption{The 1991 age distribution plotted with bullets}
+\label{fig2}
+\end{figure}
+
+Watch out for the following: the \tdescr{picture expression} is placed
+with the lower-left corner at the path knot, not its center. If you
+want it to be dead-center, you have to correct the placement
+yourself. For the example above, you need something like this instead:
+
+\medskip
+\begin{verbatim}
+def MPbullet =
+ btex \lower\fontdimen22\cmsy \hbox to 0pt{\hss\cmsy\char15\hss} etex
+enddef;
+\end{verbatim}
+
+\medskip\noindent
+followed by:
+$$ \hbox{\verb|gdraw "agepop91.d" plot MPbullet|} $$
+
+
+% glabel, gdotlabel, OUT
+
+The {\tt glabel} and {\tt gdotlabel} commands add labels to a graph. The
+syntax for {\tt glabel} is
+$$ {\tt glabel.}\ \descr{label suffix}
+ \hbox{\tt ($\descr{string or picture expression}$, $\descr{location}$)}
+ \ \descr{option list}
+$$
+where \tdescr{location} identifies the location being labeled and
+\tdescr{label suffix} tells how the label is offset relative to that location.
+The {\tt gdotlabel} command is identical, except it marks the location with a
+dot. A \tdescr{label suffix} is as in plain MetaPost:
+\tdescr{empty} centers the label on the location;
+{\tt lft}, {\tt rt}, {\tt top}, {\tt bot} offset the label horizontally or
+vertically; and {\tt ulft}, {\tt urt}, {\tt llft}, {\tt lrt} give diagonal
+offsets. The \tdescr{location} can be a pair of graph coordinates, a knot
+number on the last {\tt gdraw} path, or the special location {\tt OUT}.
+Thus
+$$ \hbox{\verb|gdotlabel.top(btex $(50,0)$ etex, 50,0)|} $$
+would put a dot at graph coordinates {\tt(50,0)} and place the typeset text
+``$(50,0)$'' above it. Alternatively,
+$$ \hbox{\verb|glabel.ulft("Knot3", 3)|} $$
+typesets the string {\tt "Knot3"} and places it above and to the left of
+Knot~3 of the last {\tt gdraw} path. (The knot number 3 the path's ``time''
+parameter~\cite[Section 8.2]{ho:mp3}.)
+
+The \tdescr{location} {\tt OUT} places a label relative to the whole graph.
+For example, replacing ``{\tt gdraw "agepop91.d"}'' with
+$$\begin{verbatim}
+glabel.lft(btex \vbox{\hbox{Population} \hbox{in millions}} etex, OUT);
+glabel.bot(btex Age in years etex, OUT);
+gdraw "agepopm.d";
+\end{verbatim}
+$$
+in the input for Figure~\ref{fig1} generates Figure~\ref{fig3}.
+This improves the graph by adding axis labels and using a new data file
+{\tt agepopm.d} where the populations have been divided by one million to avoid
+large numbers. We shall see later that simple transformations such as this can
+be achieved without generating new data files.
+
+\begin{figure}[htp]
+$$ \includegraphics{mpgraph-3.mps} $$
+\caption{An improved version of the 1991 age distribution graph}
+\label{fig3}
+\end{figure}
+
+All flavors of \TeX\ can handle multi-line labels via the \verb|\hbox| within
+\verb|\vbox| arrangement used above, but \LaTeX\ users will find it more natural
+to use the {\tt tabular} environment~\cite{LaTeXman}.
+Troff user's can use nofill mode:
+$$\begin{verbatim}
+btex .nf
+Population
+in millions etex
+\end{verbatim}
+$$
+
+
+\subsection{Coordinate Systems}
+\label{coords}
+
+The graph macros automatically shift and rescale coordinates from data files,
+{\tt gdraw} paths, and {\tt glabel} locations to fit the graph. Whether the
+range of $y$~coordinates is 0.64 to 4.6 or 640,000 to 4,600,000, they
+get scaled to fill about 88\% of the height specified in the {\tt begingraph}
+statement. Of course line widths, labels, and plotting symbols are not
+rescaled.
+
+% setrange
+
+The {\tt setrange} command controls the shifting and rescaling process by
+specifying the minimum and maximum graph coordinates:
+$$ \hbox{\tt setrange($\descr{coordinates}$,\,$\descr{coordinates}$)} $$
+where
+\begin{ctabbing}
+$\tt \descr{coordinates} \rightarrow \descr{pair expression}$\\
+$\tt \qquad \;|\; \descr{numeric or string expression}\hbox{\tt ,}
+ \descr{numeric or string expression}$
+\end{ctabbing}
+The first \tdescr{coordinates} give $(x_{\rm min},y_{\rm min})$ and the second give
+$(x_{\rm max},y_{\rm max})$. The lines $x=x_{\rm min}$, $x=x_{\rm max}$,
+$y=y_{\rm min}$, and $y=y_{\rm max}$ define the rectangular frame around the graph
+in Figures \ref{fig1}--\ref{fig3}. For example, an adding a statement
+$$ \hbox{\tt setrange(origin, whatever,\,whatever)} $$
+to the input for Figure~\ref{fig3} yields Figure~\ref{fig4}.
+The first \tdescr{coordinates} are given by the predefined pair constant
+{\tt origin}, and the other coordinates are left unspecified. Any unknown
+value would work as well, but {\tt whatever} is the standard MetaPost
+representation for an anonymous unknown value.
+
+\begin{figure}[htp]
+$$ \begin{verbatim}
+draw begingraph(3in,2in);
+ glabel.lft(btex \vbox{\hbox{Population} \hbox{in millions}} etex, OUT);
+ glabel.bot(btex Age in years etex, OUT);
+ setrange(origin, whatever,whatever);
+ gdraw "agepopm.d";
+ endgraph;
+\end{verbatim}
+\atop
+\includegraphics{mpgraph-4.mps}
+$$
+\caption{The 1991 age distribution graph and the input that creates it.}
+\label{fig4}
+\end{figure}
+
+% strings for big coordinates
+
+Notice that the syntax for {\tt setrange} allows coordinate values to be given
+as strings. Many commands in the graph package allow this option. It is
+provided because the MetaPost language uses fixed point numbers that must be
+less than 32768. This limitation is not as serious as it sounds because good
+graph design dictates that coordinate values should be ``of reasonable
+magnitude''~\cite{Cleve85,Tufte83}. If you really want $x$ and $y$
+to range from 0 to 1,000,000,
+$$ \hbox{\tt setrange(origin, "1e6",\,"1e6")} $$
+does the job. Any fixed or floating point representation is acceptable
+as long as the exponent is introduced by the letter ``{\tt e}''.
+
+% setcoords
+
+Coordinate systems need not be linear. The {\tt setcoords} command allows
+either or both axes to have logarithmic spacing:
+\begin{ctabbing}
+$\tt \descr{coordinate setting} \rightarrow setcoords\hbox{\tt (}
+ \descr{coordinate type}\hbox{\tt ,}\,\descr{coordinate type}\hbox{\tt )}$\\
+$\tt \descr{coordinate type} \rightarrow
+ log \;|\; linear \;|\; \hbox{\tt -}log \;|\; \hbox{\tt -}linear$
+\end{ctabbing}
+A negative \tdescr{coordinate type} makes $x$ (or $y$) run backwards so it is
+largest on the left side (or bottom) of the graph.
+
+Figure~\ref{fig5} graphs execution times for two matrix multiplication algorithms
+using
+$$ \hbox{\tt setcoords(log,log)} $$
+to specify logarithmic spacing on both axes. The data file {\tt matmul.d} gives
+timings for both algorithms:
+$$ \hbox to\hsize{\footnotesize\hfil$
+\begin{verbatim}
+20 .007861 standard MM: size, seconds
+30 .022051
+40 .050391
+60 .15922
+80 .4031
+120 1.53
+160 3.915
+240 18.55
+320 78.28
+480 279.24
+
+20 .006611 Strassen: size, seconds
+30 .020820
+40 .049219
+60 .163281
+80 .3975
+120 1.3125
+160 3.04
+240 9.95
+320 22.17
+480 72.60
+\end{verbatim}
+\hfil$}
+$$
+A blank line in a data file ends a data set. Subsequent {\tt gdraw} commands
+access additional data sets by just naming the same data file again.
+Since each line gives one $x$~coordinate and one $y$~coordinate, commentary
+material after the second data field on a line is ignored.
+
+\begin{figure}[htp]
+$$ \mathcenter{\includegraphics{mpgraph-5.mps}}
+ \quad
+\begin{BVerbatim}[baseline=c]
+draw begingraph(2.3in,2in);
+ setcoords(log,log);
+ glabel.lft(btex Seconds etex,OUT);
+ glabel.bot(btex Matrix size etex,
+ OUT);
+ gdraw "matmul.d" dashed evenly;
+ glabel.ulft(btex Standard etex,8);
+ gdraw "matmul.d";
+ glabel.lrt(btex Strassen etex,7);
+ endgraph;
+\end{BVerbatim}
+$$
+\caption{Timings for two matrix multiplication algorithms with the corresponding
+ MetaPost input.}
+\label{fig5}
+\end{figure}
+
+Placing a {\tt setcoords} command between two {\tt gdraw} commands graphs two
+functions in different coordinate systems as shown in Figure~\ref{fig6}.
+Whenever you give a {\tt setcoords} command, the interpreter examines what has
+been drawn, selects appropriate $x$ and $y$ ranges, and scales everything to
+fit. Everything drawn afterward is in a new coordinate system that need not
+have anything in common with the old coordinates unless {\tt setrange} commands
+enforce similar coordinate ranges. For instance, the two {\tt setrange}
+commands force both coordinate systems to have $x$ ranging from 80 to~90 and
+$y$~starting at 0.
+
+\begin{figure}[htp]
+$$ \begin{verbatim}
+draw begingraph(6.5cm,4.5cm);
+ setrange(80,0, 90,whatever);
+ glabel.bot(btex Year etex, OUT);
+ glabel.lft(btex \vbox{\hbox{Emissions in} \hbox{thousands of}
+ \hbox{metric tons} \hbox{(heavy line)}}etex, OUT);
+ gdraw "lead.d" withpen pencircle scaled 1.5pt;
+ autogrid(,otick.lft);
+ setcoords(linear,linear);
+ setrange(80,0, 90,whatever);
+ glabel.rt(btex \vbox{\hbox{Micrograms} \hbox{per cubic}
+ \hbox{meter of air} \hbox{(thin line)}}etex, OUT);
+ gdraw "lead.d";
+ autogrid(otick.bot,otick.rt);
+ endgraph;
+\end{verbatim}
+ \atop
+\mathcenter{\includegraphics{mpgraph-6.mps}}
+$$
+\caption{Annual lead emissions and average level at atmospheric monitoring
+ stations in the United States. The MetaPost input is shown above
+ the graph.}
+\label{fig6}
+\end{figure}
+
+% autogrid
+
+When you use multiple coordinate systems, you have to specify where the axis
+labels go. The default is to put tick marks on the bottom and the left side of
+the frame using the coordinate system in effect when the {\tt endgraph} command
+is interpreted. Figure~\ref{fig6} uses the
+$$ \hbox{\tt autogrid(,otick.lft)} $$
+to label the left side of the graph with the $y$~coordinates in effect before
+the {\tt setcoords} command. This suppresses the default axis labels, so another
+{\tt autogrid} command is needed to label the bottom and right sides of the
+graph using the new coordinate system. The general syntax is
+$$ \hbox{$\tt autogrid\hbox{\tt (}\descr{axis label command}\hbox{\tt ,}\,
+ \descr{axis label command}\hbox{\tt )}\ \descr{option list}$}
+$$
+where
+\begin{ctabbing}
+$\tt \descr{axis label command} \rightarrow \descr{empty}
+ \;|\; \descr{grid or tick}\, \descr{label suffix}$\\
+$\tt \descr{grid or tick} \rightarrow grid \;|\; itick \;|\; otick$
+\end{ctabbing}
+The \tdescr{label suffix} should be {\tt lft}, {\tt rt}, {\tt top},
+or {\tt bot}.
+
+The first argument to {\tt autogrid} tells how to label the $x$~axis and the
+second argument does the same for~$y$. An \tdescr{empty} argument suppresses
+labeling for that axis. Otherwise, the \tdescr{label suffix} tells which side
+of the graph gets the numeric label. Be careful to use {\tt bot} or {\tt top}
+for the $x$~axis and {\tt lft} or {\tt rt} for the $y$~axis. Use {\tt otick}
+for outward tick marks, {\tt itick} for inward tick marks, and {\tt grid} for
+grid lines. The \tdescr{option list} tells how to draw the tick marks or grid
+lines. Grid lines tend to be a little overpowering, so it is a good idea to
+give a {\tt withcolor} option to make them light gray so they do not make the
+graph too busy.
+
+
+\subsection{Explicit Grids and Framing}
+
+% otick, itick, grid, (format)
+
+In case {\tt autogrid} is not flexible enough, axis label commands generate
+grid lines or tick marks one at a time. The syntax is
+$$ \descr{grid or tick}\hbox{\tt .}\descr{label suffix}
+ \hbox{\tt ($\descr{label format}$,\,$\descr{numeric or string expression}$)}
+ \ \descr{option list}
+$$
+where \tdescr{grid or tick} and \tdescr{label suffix} are as in {\tt autogrid},
+and \tdescr{label format} is either a format string like \verb|"%g"| or a
+picture containing the typeset numeric label.
+
+The axis label commands use a macro
+$$ \hbox{\tt format($
+ \descr{format string}$,\,$\descr{numeric or string expression}$)}
+$$
+to typeset numeric labels. Full details appear in Section~\ref{formsec},
+but when the \tdescr{format string} is \verb|"%g"|, it uses decimal notation
+unless the number is large enough or small enough to require scientific notation.
+
+The example in Figure~\ref{fig7} invokes
+$$ \hbox{\verb|format("%g",y)|} $$
+explicitly so that grid lines can be placed at transformed coordinates.
+It defines the transformation ${\tt newy}(y)=y/75+\ln y$ and shows that
+this function increases almost linearly.\footnote{The manual~\cite{ho:mp3}
+explains how {\tt vardef} defines functions and {\tt mlog} computes logarithms.}
+This is a little like using logarithmic $y$-coordinates, except that $y$ is
+mapped to $y/75+\ln y$ instead of just $\ln y$.
+
+\begin{figure}[htp]
+$$ \begin{verbatim}
+vardef newy(expr y) = (256/75)*y + mlog y enddef;
+draw begingraph(3in,2in);
+ glabel.lft(btex \vbox{\hbox{Population} \hbox{in millions}} etex, OUT);
+ path p;
+ gdata("timepop.d", $, augment.p($1, newy(Scvnum $2)); );
+ gdraw p withpen nullpen;
+ for y=5,10,20,50,100,150,200,250:
+ grid.lft(format("%g",y), newy(y)) withcolor .85white;
+ endfor
+ autogrid(grid.bot,) withcolor .85white;
+ gdraw p;
+ frame.llft;
+ endgraph;
+\end{verbatim}
+ \atop
+ \includegraphics{mpgraph-7.mps}
+$$
+\caption{Population of the United States in millions versus time with the
+ population re-expressed as $p/75+\ln p$. The MetaPost input shown
+ above the graph assumes a data file {\tt ttimepop.d} that gives
+ (year, $p/75+\ln p$) pairs.}
+\label{fig7}
+\end{figure}
+
+% frame
+
+Figure~\ref{fig7} uses the command
+$$ \hbox{\tt frame.} \descr{label suffix}\ \descr{option list} $$
+to draw a special frame around the graph. In this case the \tdescr{label suffix}
+is {\tt llft} to draw just the bottom and left sides of the frame. Suffixes
+{\tt lrt}, {\tt ulft}, and {\tt urt} draw other combinations of two sides;
+suffixes {\tt lft}, {\tt rt}, {\tt top}, {\tt bot} draw one side, and \tdescr{empty}
+draws the whole frame. For example
+$$ \hbox{\verb|frame dashed evenly|} $$
+draws all four sides with dashed lines. The default four-sided frame is drawn
+only when there is no explicit {\tt frame} command.
+
+% auto, (sarith.mp)
+
+To label an axis as {\tt autogrid} does but with the labels transformed
+somehow, use
+$$ \hbox{{\tt auto.x}\quad or\quad {\tt auto.y}} $$
+for positioning tick marks or grid lines. These macros produce comma-separated
+lists for use in {\tt for} loops. Any $x$ or $y$ values in these lists that
+cannot be represented accurately within MetaPost's fixed-point number system
+are given as strings. A standard macro package that is loaded via
+$$ \hbox{\tt input sarith} $$
+defines arithmetic operators that work on numbers or strings. Binary operators
+{\tt Sadd}, {\tt Ssub}, {\tt Smul}, and {\tt Sdiv} do addition, subtraction
+multiplication, and division.
+
+One possible application is rescaling data.
+Figure~\ref{fig4} used a special data file {\tt agepopm.d} that had $y$~values
+divided by one million. This could be avoided by replacing
+``{\tt gdraw "agepopm.d"}'' by
+$$\begin{verbatim}
+gdraw "agepop91.d";
+for u=auto.y: otick.lft(format("%g",u Sdiv "1e6"), u); endfor
+autogrid(otick.bot,)
+\end{verbatim}
+$$
+
+
+\subsection{Processing Data Files}
+\label{dfilesec}
+
+% gdata
+
+The most general tool for processing data files is the {\tt gdata} command:
+$$ \hbox{\tt gdata(} \descr{string expression} \hbox{\tt,}\, \descr{variable}
+ \hbox{\tt,}\, \descr{commands} \hbox{\tt )}
+$$
+It takes a file name, a variable~$v$, and a list of commands to be executed for
+each line of the data file. The commands are executed with {\tt i} set to the
+input line number and strings $v${\tt 1}, $v${\tt 2}, $v${\tt 3}, \ldots\ set
+to the input fields on the current line. A null string marks the end of the
+$v$ array.
+
+Using a {\tt glabel} command inside of {\tt gdata} generates a scatter plot
+as shown in Figure~\ref{fig8}. The data file {\tt countries.d} begins
+$$\begin{verbatim}
+20.910 75.7 US
+ 1.831 66.7 Alg
+\end{verbatim}
+$$
+where the last field in each line gives the label to be plotted. Setting
+{\tt defaultfont} in the first line of input selects a small font for these
+labels. Without these labels, no {\tt gdata} command would be needed.
+Replacing the {\tt gdata} command with
+$$ \hbox{\verb|gdraw "countries.d" plot btex$\circ$etex|} $$
+would change the abbreviated country names to open circles.
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+defaultfont:="cmr7";
+draw begingraph(3in,2in);
+ glabel.lft(btex \vbox{\hbox{Life}\hbox{expectancy}} etex, OUT);
+ glabel.bot(btex Per capita G.N.P. (thousands of dollars) etex, OUT);
+ setcoords(log,linear);
+ gdata("countries.d", s,
+ glabel(s3, s1, s2);
+ )
+ endgraph;
+\end{verbatim}
+ \atop
+ \includegraphics{mpgraph-8.mps}
+$$
+\caption{A scatter plot and the commands that generated it}
+\label{fig8}
+\end{figure}
+
+Both {\tt gdraw} and {\tt gdata} ignore an optional initial `\%' on each input
+line, parse data fields separated by white space, and stop if they encounter an
+input line with no data fields. Leading percent signs make graph data
+look like MetaPost comments so that numeric data can be placed at the beginning
+of a MetaPost input file.
+
+% augment
+
+It is often useful to construct one or more paths when reading a data file
+with {\tt gdata}. The {\tt augment} command is designed for this:
+$$ \hbox{\tt augment.} \descr{path variable} \hbox{\tt(}\descr{coordinates}\hbox{\tt)}
+$$
+If the path variable does not have a known value, it becomes a path of length
+zero at the given coordinates; otherwise a line segment to the given coordinates
+is appended to the path. The \tdescr{coordinates} may be a pair expression or
+any combination of strings and numerics as explained at the beginning of
+Section~\ref{coords}.
+
+If a file {\tt timepop.d} gives $t$,~$p$ pairs, {\tt augment} can be used like
+this to graph {\tt newy(}$p${\tt)} versus~$t$:
+$$\begin{verbatim}
+path p;
+gdata("timepop.d", s, augment.p(s1, newy(scantokens s2)); );
+gdraw p;
+\end{verbatim}
+$$
+(MetaPost's {\tt scantokens} primitive interprets a string as if it were the
+contents of an input file. This finds the numeric value of data field
+{\tt s2}.)
+
+% gfill (energy.d)
+
+Figure~\ref{fig9} shows how to use {\tt augment} to read multiple column data
+and make multiple paths. Paths {\tt p2}, {\tt p3}, {\tt p4}, {\tt p5} give
+cumulative totals for columns 2 through 5 and pictures {\tt lab2} through
+{\tt lab5} give corresponding labels. The expression
+$$ \hbox{\verb|image(unfill bbox lab[j]; draw lab[j])|} $$
+executes the given drawing commands and returns the resulting picture:
+``{\tt unfill bbox lab[j]}'' puts down a white background and ``{\tt draw
+lab[j]}'' puts the label on the background.
+The {\tt gfill} command is just like {\tt gdraw}, except it takes a cyclic
+path and fills the interior with a solid color. The color is black unless
+a {\tt withcolor} clause specifies another color.
+See the manual~\cite{ho:mp3} for
+explanations of {\tt for} loops, arrays, colors, and path construction
+operators like \verb|--|, {\tt cycle}, and {\tt reverse}.
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+draw begingraph(3in,2in);
+ glabel.lft(btex \vbox{\hbox{Quadrillions}\hbox{of BTU}} etex, OUT);
+ path p[];
+ numeric t;
+ gdata("energy.d", $,
+ t:=0; augment.p1($1,0);
+ for j=2 upto 5:
+ t:=t+scantokens $[j]; augment.p[j]($1,t);
+ endfor)
+ picture lab[];
+ lab2=btex coal etex; lab3=btex crude oil etex;
+ lab4=btex natural gas etex; lab5=btex hydroelectric etex;
+ for j=5 downto 2:
+ gfill p[j]--reverse p[j-1]--cycle withcolor .16j*white;
+ glabel.lft(image(unfill bbox lab[j]; draw lab[j]), .7+length p[j]);
+ endfor
+ endgraph;
+\end{verbatim}
+ \atop
+ \includegraphics{mpgraph-9.mps}
+$$
+\caption{A graph of U.S. annual energy production
+ and the commands that generated it}
+\label{fig9}
+\end{figure}
+
+
+\section{Manipulating Big Numbers}
+\label{nummac}
+
+MetaPost inherits a fixed-point number system from Knuth's \MF~\cite{kn:d}.
+Numbers are expressed in multiples of $2^{-16}$ and they must have absolute
+value less than 32768. Knuth chose this system because it is perfectly adequate
+for font design, and it guaranteed to give identical results on all types of
+computers. Fixed-point numbers are seldom a problem in MetaPost because all
+computations are based on coordinates that are limited by the size the paper on
+which the output is to be printed. This does not hold for the input data in a
+graph-drawing application. Although graphs look best when coordinate axes are
+labeled with numbers of reasonable magnitude, the strict limits of fixed-point
+arithmetic would be inconvenient.
+
+% Sadd, Ssub, Smul, Sdiv
+
+A simple way to handle large numbers is to include the line
+$$ \hbox{\tt input sarith} $$
+and then use binary operators {\tt Sadd}, {\tt Ssub}, {\tt Smul}, and {\tt Sdiv}
+in place of \verb|+|, \verb|-|, \verb|*|, and \verb|/|. These operators are
+inefficient but very flexible. They accept numbers or strings and return
+strings in exponential notation with the exponent marked by ``{\tt e}'';
+e.g., \verb|"6.7e-11"| means $6.7\times10^{-11}$.
+
+% Sabs, Sleq, Sneq
+
+The unary operator\footnote{The argument to a unary operator need not be
+parenthesized unless it is an expression involving binary operators.}
+$$ {\tt Sabs}\ \descr{string} $$
+finds a string the represents the absolute value. Binary operators {\tt Sleq}
+and {\tt Sneq} perform numeric comparisons on strings and return boolean
+results.
+
+% Scvnum
+
+The operation
+$$ {\tt Scvnum}\ \descr{string} $$
+finds the numeric value for a string if this can be done without overflowing
+MetaPost's fixed-point number system. If the string does not contain
+``{\tt e}'', it is much more efficient to use the primitive operation
+$$ {\tt scantokens}\ \descr{string} $$
+
+% Mten
+
+The above operators are based on a low-level package that manipulates numbers
+in ``{\tt Mlog} form.'' A number $x$ in {\tt Mlog} form represents
+$$ \mu^{2^{16}x}, \quad {\rm where\ } \mu=-e^{2^{-24}}. $$
+Any value between $1.61\times10^{-28}$ and $3.88\times10^{55}$ can be
+represented this way. (There is a constant {\tt Mten} such that $k*{\tt Mten}$
+represents $10^k$ for any integer~$k$ in the interval $[-29,55]$.)
+
+% Mreadpath, Gpaths
+
+The main reason for mentioning {\tt Mlog} form is that it allows graph data
+to be manipulated as a MetaPost path. The function
+$$ \hbox{\tt Mreadpath($\descr{file name}$)} $$
+reads a data file and returns a path where all the coordinates are in
+{\tt Mlog} form. An internal variable {\tt Gpaths} determines whether
+{\tt gdraw} and {\tt gfill} expect paths to be given in {\tt Mlog} form.
+For example, this graphs the data in {\tt agepop91.d} with $y$ coordinates
+divided by one million:
+$$\begin{verbatim}
+interim Gpaths:=log;
+gdraw Mreadpath("agepop91.d") shifted (0,-6*Mten);
+\end{verbatim}
+$$
+
+
+\section{Typesetting Numbers}
+\label{formsec}
+
+% format
+
+The graph package needs to compute axis labels and then typeset them.
+The macro
+$$ \hbox{\tt format($\descr{string expression}$,\,%
+ $\descr{numeric or string expression}$)} $$
+does this. You must first {\tt input graph} or {\tt input format} to load the
+macro file. The macro takes a format string and a number to typeset and returns
+a picture containing the typeset result. Thus
+$$ \hbox{\verb|format("%g",2+2)|}\quad {\rm yields}\quad \includegraphics{mpgraph-10.mps} $$
+and
+$$ \hbox{\verb|format("%3g","6.022e23")|}
+ \quad {\rm yields}\quad \includegraphics{mpgraph-11.mps}
+$$
+
+A format string consists of
+\begin{itemize}
+\item an optional initial string not containing a percent sign,
+\item a percent sign,
+\item an optional numeric precision $p$,
+\item one of the conversion letters {\tt e}, {\tt f}, {\tt g}, {\tt G},
+\item an optional final string $\beta$.
+\end{itemize}
+The initial and final strings are typeset in the default font (usually
+{\tt cmr10}), and the typeset number is placed between them. For the {\tt e}
+and {\tt g} formats, the precision~$p$ is the number of significant digits
+allowed after rounding; for {\tt f} and {\tt G}, the number is rounded to the
+nearest multiple of $10^{-p}$. If the precision is not specified, the default
+is $p=3$. The {\tt e} format always uses scientific
+notation and the {\tt f} format uses ordinary decimal notation but reverts to
+scientific notation if the number is at least 10000. The {\tt g} and {\tt G}
+formats also revert to scientific notation for non-zero numbers of magnitude
+less than 0.001.
+
+% init_numbers
+
+The {\tt format} macro needs a set of templates to determine what font to use,
+how to position the exponent, etc. The templates are normally initialized
+automatically, but it is possible to set them explicitly by passing five picture
+expressions to {\tt init\_numbers}. For instance, the default definition for
+\TeX\ users is
+$$\begin{verbatim}
+init_numbers(btex$-$etex, btex$1$etex, btex${\times}10$etex,
+ btex${}^-$etex, btex${}^2$etex)
+\end{verbatim}
+$$
+The first argument tells how to typeset a leading minus sign;
+the second argument is an example of a 1-digit mantissa;
+third comes whatever to put after the mantissa in scientific notation;
+next come a leading minus sign for the exponent and a sample 1-digit exponent.
+
+% Fe_plus, Fe_base
+
+Picture variable \verb|Fe_plus| gives a leading plus sign for positive numbers,
+and \verb|Fe_base| gives whatever should precede the exponent when typesetting
+a power of ten. Calling \verb|init_numbers| initializes \verb|Fe_plus| to an
+empty picture and constructs \verb|Fe_base| from its second and third arguments.
+
+
+
+\section{Conclusion}
+\label{concl}
+
+The graph package makes it convenient to generate graphs from within the MetaPost
+language. The primary benefits are the power of the MetaPost language and its
+ability to interact with \TeX\ or troff for typesetting labels. Typeset labels
+can be stored in picture variables and manipulated in various ways such measuring
+the bounding box and providing a white background.
+
+We have seen how to generate shaded regions and control line width, color, and
+styles of dashed lines. Numerous other variations are possible.
+The full MetaPost language~\cite{ho:mp3} provides many other potentially useful
+features. It also has enough computing power to be useful for generating and
+processing data.
+
+
+
+\appendix
+\section{Summary of the Graph Package}
+\label{summsec}
+
+% Not described elsewhere: gdrawarrow, gdrawdblarrow, Gmarks, Gminlog, Autoform
+
+In the following descriptions, italic letters such as $w$ and $h$ denote
+expression parameters and words in angle brackets denote other syntactic
+elements. Unless specified otherwise, expression parameters can be either
+numerics or strings. An \tdescr{option list} is a list of drawing options such
+as {\tt withcolor .5white} or {\tt dashed evenly};
+a \tdescr{label suffix} is one of {\tt lft}, {\tt rt}, {\tt top}, {\tt bot},
+{\tt ulft}, {\tt urt}, {\tt llft}, {\tt lrt}.
+
+\subsection{Graph Administration}
+
+\begin{description}
+\item[{\tt begingraph($w$,$h$)}]
+ Begin a new graph with the frame width and height given by numeric
+ parameters $w$ and $h$.
+\item[{\tt endgraph}]
+ End a graph and return the resulting picture.
+\item[{\tt setcoords($t_x$,\,$t_y$)}]
+ Set up a new coordinate system as specified by numeric flags $t_x$,
+ $t_y$. Flag values are $\pm{\tt linear}$ and $\pm{\tt log}$.
+\item[{\tt setrange($\descr{coordinates}$,\,$\descr{coordinates}$)}]
+ Set the lower and upper limits for the current coordinate system.
+ Each \tdescr{coordinates} can be a single pair expression or two
+ numeric or string expressions.
+\end{description}
+
+\subsection{Drawing and Labeling}
+
+All of the drawing and labeling commands can be followed by an
+\tdescr{option list}. In addition to the usual MetaPost drawing options, the
+list can contain a {\tt plot} \tdescr{picture} clause to plot a specified
+picture at each data point.
+
+The drawing and labeling commands are closely related to a set of similarly
+named commands in plain MetaPost. The {\tt gdrawarrow} and {\tt gdrawdblarrow}
+commands are included to maintain this relationship.
+
+\begin{description}
+\item[{\tt gdotlabel.$\descr{label suffix}$($p$,\,$\descr{location}$)}]
+ This is like {\tt glabel} except it also puts a dot at the location
+ being labeled.
+\item[{\tt gdraw $p$}]
+ Draw path $p$, or if $p$ is a string, read coordinate pairs from
+ file~$p$ and draw a polygonal line through them.
+\item[{\tt gdrawarrow $p$}]
+ This is like {\tt dgraw} $p$ except it adds an arrowhead at the end of
+ the path.
+\item[{\tt gdrawdblarrow $p$}]
+ This is like {\tt dgraw} $p$ except it adds an arrowheads at each end of
+ the path.
+\item[{\tt gfill $p$}]
+ Fill cyclic path~$p$ or read coordinates from the file named by
+ string~$p$ and fill the resulting polygonal outline.
+\item[{\tt glabel.$\descr{label suffix}$($p$,\,$\descr{location}$)}]
+ If $p$ is not a picture, it should be a string. Typeset it using
+ {\tt defaultfont}, then place it near the given location and offset as
+ specified by the \tdescr{label suffix}. The \tdescr{location} can be
+ $x$~and $y$ coordinates, a pair giving $x$~and $y$, a numerc value giving
+ a time on the last path drawn, or {\tt OUT} to label the outside of the
+ graph.
+\end{description}
+
+\subsection{Grids, Tick Marks, and Framing}
+
+\begin{description}
+\item[{\tt auto.}$\descr{{\tt x} or {\tt y}}$]
+ Generate default $x$ or $y$ coordinates for tick marks.
+\item[{\tt autogrid($\descr{axis label command}$,\,$\descr{axis label command}$)}]
+ Draw default axis labels using the specified commands for the $x$ and
+ $y$ axes. An \tdescr{axis label command} may be \tdescr{empty} or it
+ may be {\tt itick}, {\tt otick}, or {\tt grid} followed by a
+ \tdescr{label suffix}.
+\item[{\tt frame.}$\descr{label suffix}$\ $\descr{option list}$]
+ Draw a frame around the graph, or draw the part of the frame specified
+ by the \tdescr{label suffix}.
+\item[{\tt grid.}$\descr{label suffix}$($f$,$z$)]
+ Draw a grid line across the graph from the side specified by the
+ \tdescr{label suffix}, and label it there using format string~$f$ and
+ coordinate value~$z$. If $f$ is a picture, it gives the label.
+\item[{\tt itick.}$\descr{label suffix}$($f$,$z$)]
+ This is like {\tt grid} except it draws an inward tick mark.
+\item[{\tt otick.}$\descr{label suffix}$($f$,$z$)]
+ This is like {\tt grid} except it draws an outward tick mark.
+\end{description}
+
+\subsection{Miscellaneous Commands}
+
+\begin{description}
+\item[{\tt augment.$\descr{variable}$($\descr{coordinates}$)}]
+ Append \tdescr{coordinates} to the path stored in \tdescr{variable}.
+\item[{\tt format($f$,\,$x$)}]
+ Typeset $x$ according to format string~$f$ and return the resulting
+ picture.
+\item[{\tt gdata($f$,\,$\descr{variable}$,\,$\descr{commands}$)}]
+ Read the file named by string~$f$ and execute \tdescr{commands} for each
+ input line using the \tdescr{variable} as an array to store data fields.
+\item[{\tt init\_numbers($s$,\,$m$,\,$x$,\,$t$,\,$e$)}]
+ Provide five pictures as templates for future {\tt format} operations:
+ $s$ is a leading minus; $m$ is a sample mantissa; $x$ follows the
+ mantissa; $t$ is a leading minus for the exponent~$e$.
+\item[{\tt Mreadpath($f$)}]
+ Read a path for the data file named by string~$f$ and return it in
+ ``{\tt Mlog} form''.
+\end{description}
+
+\subsection{Arithmetic on Numeric Strings}
+
+It is necessary to {\tt input sarith} before using the following macros:
+\begin{description}
+\item[{\tt Sabs $x$}]
+ Compute $|x|$ and return a numeric string.
+\item[{\tt $x$ Sadd $y$}]
+ Compute $x+y$ and return a numeric string.
+\item[{\tt Scvnum $x$}]
+ Return the numeric value for string $x$.
+\item[{\tt $x$ Sdiv $y$}]
+ Compute $x/y$ and return a numeric string.
+\item[{\tt $x$ Sleq $y$}]
+ Return the boolean result of the comparison $x\leq y$.
+\item[{\tt $x$ Smul $y$}]
+ Compute $x*y$ and return a numeric string.
+\item[{\tt $x$ Sneq $y$}]
+ Return the boolean result of the comparison $x\neq y$.
+\item[{\tt $x$ Ssub $y$}]
+ Compute $x-y$ and return a numeric string.
+\end{description}
+
+\subsection{Internal Variables and Constants}
+
+\begin{description}
+\item[{\tt Autoform}]
+ Format string used by {\tt autogrid}. Default: \verb|"%g"|.
+\item[{\tt Fe\_base}]
+ What precedes the exponent when typesetting a power of ten.
+\item[{\tt Fe\_plus}]
+ Picture of the leading plus sign for positive exponents.
+\item[{\tt Gmarks}]
+ Minimum number of tick marks per axis for {\tt auto} and {\tt autogrid}.
+ Default: 4.
+\item[{\tt Gminlog}]
+ Minimum largest/smallest ratio for logarithmic spacing with {\tt auto}
+ and {\tt autogrid}. Default: 3.0.
+\item[{\tt Gpaths}]
+ Code for coordinates used in {\tt gdraw} and {\tt gfill} paths:
+ {\tt linear} for standard form, {log} for ``{\tt Mlog} form''.
+\item[{\tt Mten}]
+ The ``{\tt Mlog} form'' for 10.0
+\end{description}
+
+
+\bibliographystyle{plain}
+\bibliography{mpgraph}
+
+\end{document}
+
+
+
+% Copyright 1990 - 1995 by AT&T Bell Laboratories.
+
+% Permission to use, copy, modify, and distribute this software
+% and its documentation for any purpose and without fee is hereby
+% granted, provided that the above copyright notice appear in all
+% copies and that both that the copyright notice and this
+% permission notice and warranty disclaimer appear in supporting
+% documentation, and that the names of AT&T Bell Laboratories or
+% any of its entities not be used in advertising or publicity
+% pertaining to distribution of the software without specific,
+% written prior permission.
+
+% AT&T disclaims all warranties with regard to this software,
+% including all implied warranties of merchantability and fitness.
+% In no event shall AT&T be liable for any special, indirect or
+% consequential damages or any damages whatsoever resulting from
+% loss of use, data or profits, whether in an action of contract,
+% negligence or other tortious action, arising out of or in
+% connection with the use or performance of this software.
+
+% In addition, John Hobby, the original author of MetaPost and this
+% manual, makes the following requests:
+% - I request that it remain clear that I am the author of
+% "A User's Manual for MetaPost" and "Drawing Graphs with MetaPost".
+% - I request to be consulted before significant changes are made.
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-PDF-mode: t
+%%% TeX-master: t
+%%% End:
diff --git a/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 <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#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 <math.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#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
+<string> s = mplib.version()
+\stoptyping
+
+\subsection{\luatex{mplib.new}}
+
+To create a new metapost instance, call
+
+\starttyping
+<mpinstance> mp = mplib.new({...})
+\stoptyping
+
+This creates the \type{mp} instance object. The \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
+<string> found = finder (<string> name, <string> mode, <string> type)
+\stoptyping
+
+with:
+
+\starttabulate[|lT|l|p|]
+\NC name \NC the requested file \NC \NR
+\NC mode \NC the file mode: \type {r} or \type {w} \NC \NR
+\NC type \NC the kind of file, one of: \type {mp}, \type {tfm}, \type {map}, \type {pfb}, \type {enc} \NC \NR
+\stoptabulate
+
+Return either the full pathname of the found file, or \type{nil} if
+the file cannot be found.
+
+\subsection{\luatex{mp:statistics}}
+
+You can request statistics with:
+
+\starttyping
+<table> stats = mp:statistics()
+\stoptyping
+
+This function returns the 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
+<number> w = mp.char_width(<string> fontname, <number> char)
+\stoptyping
+
+\subsubsection{\luatex{mp.char_height}}
+
+\starttyping
+<number> w = mp.char_height(<string> fontname, <number> char)
+\stoptyping
+
+\subsubsection{\luatex{mp.char_depth}}
+
+\starttyping
+<number> w = mp.char_depth(<string> fontname, <number> char)
+\stoptyping
+
+\subsection{Solving path control points}
+
+\starttyping
+<boolean> success = mp.solve_path(<table> knots, <boolean> 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{<?\texttt{<}} =\index{=?\texttt{=}} >\index{>?\texttt{>}}\par <=\index{<=?\texttt{<=}} >=\index{>=?\texttt{>=}}\par <>\index{<>?\texttt{<>}}& string\par numeric\par pair\par (cmyk)color\par transform& string\par numeric\par pair\par (cmyk)color\par transform& boolean& \pageref{Dcmpar}& Comparison operators\\\hline
+\pl abs\index{abs?\texttt{abs}}& --& numeric\par pair& numeric& \pageref{Dabs}& Absolute value\par Euclidean length $\sqrt{(\mbox{\ttfamily xpart\ } r)^2+(\mbox{\ttfamily ypart\ } r)^2}$\\\hline
+and\index{and?\texttt{and}}& boolean& boolean& boolean& \pageref{Dand}& Logical and\\\hline
+angle\index{angle?\texttt{angle}}& --& pair& numeric& \pageref{Dangle}& 2$-$argument arctangent (in degrees)\\\hline
+arclength\index{arclength?\texttt{arclength}}& --& path& numeric& \pageref{Darclng}& Arc length of a path\\\hline
+arctime of\index{arctime of?\texttt{arctime of}}& numeric& path& numeric& \pageref{Darctim}& Time on a path where arc length from the start reaches a given value\\\hline
+ASCII\index{ASCII?\texttt{ASCII}}& --& string& numeric& --& ASCII value of first character in string\\\hline
+\pl bbox\index{bbox?\texttt{bbox}}& --& picture\par path\par pen& path& \pageref{Dbbox}& A rectangular path for the bounding box\\\hline
+blackpart\index{blackpart?\texttt{blackpart}}& --& cmykcolor& numeric& \pageref{Dcmykprt}& Extract the fourth component\\\hline
+bluepart\index{bluepart?\texttt{bluepart}}& --& color& numeric& \pageref{Drgbprt}& Extract the third component\\\hline
+boolean\index{boolean?\texttt{boolean}}& --& any& boolean& \pageref{Dboolop}& Is the expression of type boolean?\\\hline
+\pl bot\index{bot?\texttt{bot}}& --& numeric\par pair& numeric\par pair& \pageref{Dbot}& Bottom of current pen when centered at the given coordinate(s)\\\hline
+bounded\index{bounded?\texttt{bounded}}& --& any& boolean& \pageref{Dbounded}& Is argument a picture with a bounding box?\\\hline
+\pl ceiling\index{ceiling?\texttt{ceiling}}& --& numeric& numeric& \pageref{Dceil}& Least integer greater than or equal to\\\hline
+\pl center\index{center?\texttt{center}}& --& picture\par path\par pen& pair& \pageref{Dcenter}& Center of the bounding box\\\hline
+char\index{char?\texttt{char}}& --& numeric& string& \pageref{Dchar}& Character with a given ASCII code\\\hline
+clipped\index{clipped?\texttt{clipped}}& --& any& boolean& \pageref{Dclipped}& Is argument a clipped picture?\\\hline
+cmykcolor\index{cmykcolor?\texttt{cmykcolor}}& --& any& boolean& \pageref{Dccolrop}& Is the expression of type cmykcolor?\\\hline
+color\index{color?\texttt{color}}& --& any& boolean& \pageref{Dcolrop}& Is the expression of type color?\\\hline
+colormodel\index{colormodel?\texttt{colormodel}}& --& image object& numeric& \pageref{Dcolormodel}& What is the color model of the image object?\\\hline
+\pl colorpart\index{colorpart?\texttt{colorpart}}& --& image object&
+(cmyk)color\par numeric\par boolean& \pageref{Dcolorpart}& What is the
+color of the image object?\\\hline
+cosd\index{cosd?\texttt{cosd}}& --& numeric& numeric& \pageref{Dcosd}& Cosine of angle in degrees\\\hline
+\pl cutafter\index{cutafter?\texttt{cutafter}}& path& path& path& \pageref{Dcuta}& Left argument with part after the intersection dropped\\\hline
+\pl cutbefore\index{cutbefore?\texttt{cutbefore}}& path& path& path& \pageref{Dcutb}& Left argument with part before the intersection dropped\\\hline
+cyanpart\index{cyanpart?\texttt{cyanpart}}& --& cmykcolor& numeric& \pageref{Dcmykprt}& Extract the first component\\\hline
+cycle\index{cycle?\texttt{cycle}}& --& path& boolean& \pageref{Dcycop}& Determines whether a path is cyclic\\\hline
+dashpart\index{dashpart?\texttt{dashpart}}& --& picture& picture& \pageref{Ddashpart}& Dash pattern of a path in a stroked picture\\\hline
+decimal\index{decimal?\texttt{decimal}}& --& numeric& string& \pageref{Ddecop}& The decimal representation\\\hline
+\pl dir\index{dir?\texttt{dir}}& --& numeric& pair& \pageref{Ddirop}& $(\cos\theta,\sin\theta)$ given $\theta$ in degrees\\\hline
+\pl direction of\index{direction of?\texttt{direction of}}& numeric& path& pair& \pageref{Ddirof}& The direction of a path at a given `time'\\\hline
+\pl direction\-point of\index{directionpoint of?\texttt{directionpoint of}}& pair& path& numeric& \pageref{Ddpntof}& Point where a path has a given direction\\\hline
+direction\-time of\index{directiontime of?\texttt{directiontime of}}& pair& path& numeric& \pageref{Ddtimof}& `Time' when a path has a given direction\\\hline
+\pl div\index{div?\texttt{div}}& numeric& numeric& numeric& --& Integer division $\lfloor l/r\rfloor$\\\hline
+\pl dotprod\index{dotprod?\texttt{dotprod}}& pair& pair& numeric& \pageref{Ddprod}& Vector dot product\\\hline
+filled\index{filled?\texttt{filled}}& --& any& boolean& \pageref{Dfilled}& Is argument a filled outline?\\\hline
+floor\index{floor?\texttt{floor}}& --& numeric& numeric& \pageref{Dfloor}& Greatest integer less than or equal to\\\hline
+fontpart\index{fontpart?\texttt{fontpart}}& --& picture& string& \pageref{Dfontpart}& Font of a textual picture component\\\hline
+fontsize\index{fontsize?\texttt{fontsize}}& --& string& numeric& \pageref{Dfntsiz}& The point size of a font\\\hline
+glyph of\index{glyph?\texttt{glyph}}& numeric\par string& string& picture&
+\pageref{Dglyph}& Convert a glyph of a font to contours\\\hline
+greenpart\index{greenpart?\texttt{greenpart}}& --& color& numeric& \pageref{Drgbprt}& Extract the second component\\\hline
+greypart\index{greypart?\texttt{greypart}}& --& numeric& numeric& \pageref{Dgreyprt}& Extract the first (only) component\\\hline
+hex\index{hex?\texttt{hex}}& --& string& numeric& --& Interpret as a hexadecimal number\\\hline
+infont\index{infont?\texttt{infont}}& string& string& picture& \pageref{Sinfont}& Typeset string in given font\\\hline
+\pl intersec\-tionpoint\index{intersectionpoint?\texttt{intersectionpoint}}& path& path& pair& \pageref{Disecpt}& An intersection point\\\hline
+intersec\-tiontimes\index{intersectiontimes?\texttt{intersectiontimes}}& path& path& pair& \pageref{Disectt}& Times ($t_l,t_r)$ on paths $l$ and $r$ when the paths intersect\\\hline
+\pl inverse\index{inverse?\texttt{inverse}}& --& transform& transform& \pageref{Dinv}& Invert a transformation\\\hline
+known\index{known?\texttt{known}}& --& any& boolean& \pageref{Dknown}& Does argument have a known value?\\\hline
+length\index{length?\texttt{length}}& --& path\par string\par picture& numeric& \pageref{Dlength}\par \pageref{DlengthString}\par \pageref{DlengthPicture}& Number of components (arcs, characters, strokes, \ldots) in the argument\\\hline
+\pl lft\index{lft?\texttt{lft}}& --& numeric\par pair& numeric\par pair& \pageref{Dlft}& Left side of current pen when its center is at the given coordinate(s)\\\hline
+llcorner\index{llcorner?\texttt{llcorner}}& --& picture\par path\par pen& pair& \pageref{Dcornop}& Lower-left corner of bounding box\\\hline
+lrcorner\index{lrcorner?\texttt{lrcorner}}& --& picture\par path\par pen& pair& \pageref{Dcornop}& Lower-right corner of bounding box\\\hline
+magentapart\index{magentapart?\texttt{magentapart}}& --& cmykcolor& numeric& \pageref{Dcmykprt}& Extract the second component\\\hline
+makepath\index{makepath?\texttt{makepath}}& --& pen& path& \pageref{Dmkpath}& Cyclic path bounding the pen shape\\\hline
+makepen\index{makepen?\texttt{makepen}}& --& path& pen& \pageref{Dmkpen}& A polygonal pen made from the convex hull of the path knots\\\hline
+mexp\index{mexp?\texttt{mexp}}& --& numeric& numeric& --& The function $\exp(x/256)$\\\hline
+mlog\index{mlog?\texttt{mlog}}& --& numeric& numeric& --& The function $256\ln(x)$\\\hline
+\pl mod\index{mod?\texttt{mod}}& --& numeric& numeric& --& The remainder function $l-r\lfloor l/r\rfloor$\\\hline
+normal\-deviate\index{normaldeviate?\texttt{normaldeviate}}& --& --& numeric& --& Choose a random number with mean~0 and standard deviation~1\\\hline
+not\index{not?\texttt{not}}& --& boolean& boolean& \pageref{Dnot}& Logical negation\\\hline
+numeric\index{numeric?\texttt{numeric}}& --& any& boolean& \pageref{Dnumop}& Is the expression of type numeric?\\\hline
+oct\index{oct?\texttt{oct}}& --& string& numeric& --& Interpret string as octal number\\\hline
+odd\index{odd?\texttt{odd}}& --& numeric& boolean& --& Is the closest integer odd or even?\\\hline
+or\index{or?\texttt{or}}& boolean& boolean& boolean& \pageref{Dor}& Logical inclusive or\\\hline
+pair\index{pair?\texttt{pair}}& --& any& boolean& \pageref{Dpairop}& Is the expression of type pair?\\\hline
+path\index{path?\texttt{path}}& --& any& boolean& \pageref{Dpathop}& Is the expression of type path?\\\hline
+pathpart\index{pathpart?\texttt{pathpart}}& --& picture& path& \pageref{Dpathpart}& Path of a stroked picture component\\\hline
+pen\index{pen?\texttt{pen}}& --& any& boolean& \pageref{Dpenop}& Is the expression of type pen?\\\hline
+penoffset of\index{penoffset of?\texttt{penoffset of}}& pair& pen& pair& --& Point on the pen furthest to the right of the given direction\\\hline
+penpart\index{penpart?\texttt{penpart}}& --& picture& pen& \pageref{Dpenpart}& Pen of a stroked picture component\\\hline
+picture\index{picture?\texttt{picture}}& --& any& boolean& \pageref{Dpictop}& Is the expression of type picture?\\\hline
+point of\index{point of?\texttt{point of}}& numeric& path& pair& \pageref{Dpntof}& Point on a path given a time value\\\hline
+postcontrol of\index{postcontrol 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
+% <URL:http://www.openclipart.org/about>. The original SVG file by
+% 'yyycatch' is licensed as Public Domain and can be found at
+% <URL:http://www.openclipart.org/detail/18601>. 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<angle_radius: s:=angle_radius; fi
+ draw_marked(p scaled s shifted b, n);
+ endgroup
+enddef;
+
+def mark_rt_angle(expr a, b, c) =
+ draw ((1,0)--(1,1)--(0,1))
+ zscaled (angle_radius*unitvector(a-b)) shifted b
+enddef;
+
+beginfig(42);
+pair a,b,c,d;
+b=(0,0); c=(1.5in,0); a=(0,.6in);
+d-c = (a-b) rotated 25;
+dotlabel.lft("a",a);
+dotlabel.lft("b",b);
+dotlabel.bot("c",c);
+dotlabel.llft("d",d);
+z0=.5[a,d];
+z1=.5[b,c];
+(z.p-z0) dotprod (d-a) = 0;
+(z.p-z1) dotprod (c-b) = 0;
+draw a--d;
+draw b--c;
+draw z0--z.p--z1;
+draw_marked(a--b, 1);
+draw_marked(c--d, 1);
+draw_marked(a--z.p, 2);
+draw_marked(d--z.p, 2);
+draw_marked(b--z.p, 3);
+draw_marked(c--z.p, 3);
+mark_angle(z.p, b, a, 1);
+mark_angle(z.p, c, d, 1);
+mark_angle(z.p, c, b, 2);
+mark_angle(c, b, z.p, 2);
+mark_rt_angle(z.p, z0, a);
+mark_rt_angle(z.p, z1, b);
+endfig;
+
+
+def getmid(suffix p) =
+ pair p.mid[], p.off[], p.dir[];
+ for i=0 upto 36:
+ p.dir[i] = dir(5*i);
+ p.mid[i]+p.off[i] = directionpoint p.dir[i] of p;
+ p.mid[i]-p.off[i] = directionpoint -p.dir[i] of p;
+ endfor
+enddef;
+
+def joinup(suffix pt, d)(expr n) =
+ begingroup
+ save res, g; path res;
+ res = pt[0]{d[0]};
+ for i=1 upto n:
+ g:= if (pt[i]-pt[i-1]) dotprod d[i] <0: - fi 1;
+ res := res{g*d[i-1]}...{g*d[i]}pt[i];
+ endfor
+ res
+ endgroup
+enddef;
+
+beginfig(45)
+path p, q;
+p = ((5,2)...(3,4)...(1,3)...(-2,-3)...(0,-5)...(3,-4)
+ ...(5,-3)...cycle) scaled .3cm shifted (0,5cm);
+getmid(p);
+draw p;
+draw joinup(p.mid, p.dir, 36)..cycle;
+q = joinup(p.off, p.dir, 36);
+draw q..(q rotated 180)..cycle;
+drawoptions(dashed evenly);
+for i=0 upto 3:
+ draw p.mid[9i]-p.off[9i]..p.mid[9i]+p.off[9i];
+ draw -p.off[9i]..p.off[9i];
+endfor
+endfig;
+
+
+beginfig(55)
+picture wheel, car;
+path body;
+ u := 5bp;
+ % Use a calligraphic pen.
+ pickup pencircle scaled .1u yscaled .6 rotated 30;
+ % Define a wheel object.
+ wheel := image(
+ draw fullcircle scaled 2u xscaled .8 rotated 30;
+ draw fullcircle scaled .1u xscaled .8 rotated 30
+ withpen currentpen scaled .5;
+ );
+ % Construct path for car body.
+ body := (3.2u,0){right}..(4.5u,1.5u){up}..(1.5u,2.5u){dir(-170)}
+ ..(1.5u,4.25u){up}...(0,5u){left};
+ body := body .. reverse body reflectedabout (origin, (0,u));
+ % Define a car object.
+ car := image(
+ draw wheel shifted (2u, 0);% Draw two wheels.
+ draw wheel shifted (-2u, 0);
+ draw (-.8u,0){dir(5)}..(.8u,0);% Draw connection betweeen wheels.
+ draw body;% Draw body.
+ % Draw speed indicators.
+ for i=1.5, 2, 2.5:
+ draw (5u, u*i){right}..{dir(-10)}(6.5u,u*i*.95);
+ endfor
+ ) shifted (0, u) slanted -.2 rotated 1;% Introduce asymmetries.
+ % Draw two cars and a faster one.
+ draw car shifted (5u,0);
+ draw car shifted (20u,0);
+ draw car slanted -.25 shifted (45u,0);
+ % Draw motorway.
+ draw (-5u,-u)...(25u,-.5u)...(60u,-u)
+ withpen currentpen scaled 4 withcolor .7white;
+endfig;
+
+
+fontmapfile "=lm-ec.map";
+beginfig(56);
+ picture q;
+ path p;
+ interim ahlength := 12bp;
+ interim ahangle := 25;
+ q := glyph "Dcaron" of "ec-lmr10" scaled .2;
+ for item within q:
+ p := pathpart item;
+ drawarrow p withcolor (.6,.9,.6)
+ withpen pencircle scaled 1.5;
+ for j=0 upto length p:
+ pickup pencircle scaled .7;
+ draw (point j of p -- precontrol j of p)
+ dashed evenly withcolor blue;
+ draw (point j of p -- postcontrol j of p)
+ dashed evenly withcolor blue;
+ pickup pencircle scaled 3;
+ draw precontrol j of p withcolor red;
+ draw postcontrol j of p withcolor red;
+ pickup pencircle scaled 2;
+ draw point j of p withcolor black;
+ endfor
+ endfor
+endfig;
+
+
+%%% Title page rule.
+beginfig(60);
+ pickup pencircle scaled 1.1bp;
+ linecap := rounded;
+ draw origin--(4.38in,0);
+endfig;
+
+
+beginfig(61);
+ def shape_with_cardinal_points(expr shape) =
+ image(
+ interim ahangle := 30;
+ interim ahlength := 6bp;
+ drawarrow shape withpen pencircle scaled .5;
+ for k = 0 upto length shape:
+ drawdot point k of shape withpen pencircle scaled dotlabeldiam;
+ endfor
+ )
+ enddef;
+
+ draw shape_with_cardinal_points(fullcircle scaled 1in);
+ draw shape_with_cardinal_points(unitsquare scaled 1in) withcolor .5white;
+endfig;
+
+end
diff --git a/systems/doc/metapost/source-manual/mpman.tex b/systems/doc/metapost/source-manual/mpman.tex
new file mode 100644
index 0000000000..ec77468753
--- /dev/null
+++ b/systems/doc/metapost/source-manual/mpman.tex
@@ -0,0 +1,6008 @@
+% $Id: mpman.tex 2139 2018-02-19 14:38:47Z luigi.scarso@gmail.com $
+% MetaPost manual, by John Hobby. License at end.
+\listfiles
+\RequirePackage{ifpdf}
+\ifpdf
+\ifnum\pdftexversion<140
+\else
+\pdfminorversion=5
+\pdfobjcompresslevel=1% Use compressed object streams.
+\fi
+\RequirePackage{cmap}
+\fi
+\documentclass{article} % article is NOT the original style
+\usepackage[nofancy]{svninfo}% Access VCS information.
+\svnInfo $Id: mpman.tex 2140 2019-06-01 14:38:47Z luigi.scarso@gmail.com $
+%\svnInfo $Id: mpman.tex 2139 2018-02-19 14:38:47Z luigi.scarso@gmail.com $
+\newcommand*{\mpversion}{2.00}
+
+\usepackage[T1]{fontenc}
+\usepackage{lmodern}
+\usepackage{textcomp}
+\usepackage{mflogo}
+\usepackage{makeidx}
+\usepackage{fancyvrb}
+\usepackage{ctabbing}
+\RecustomVerbatimEnvironment
+ {verbatim}{BVerbatim}{baseline=c}
+\usepackage{graphicx}
+\usepackage[latin1]{inputenc}
+\usepackage[textwidth=6in,textheight=8.65in]{geometry}
+\usepackage{tocloft}
+ \setlength\cftbeforesecskip{1.3ex plus 0.3ex minus 0.3ex}
+ \setcounter{tocdepth}{2}
+\usepackage{ltxtable}
+
+
+\def\ttindex#1{{\tt #1}\index{#1?\texttt{#1}}}
+\def\ttt{\texttt} % I get tired of typing this out
+
+\def\ConTeXt{Con\TeX t}
+
+\newcommand\descr[1]{{\langle\hbox{#1}\rangle}}
+\newcommand\invisgap{\nobreak\hskip0pt\relax}
+\newcommand\tdescr[1]{{\normalfont$\langle$\invisgap#1\invisgap$\rangle$}}
+
+\newcommand\pl{\dag}
+
+\newcommand\mathcenter[1]{\vcenter{\hbox{#1}}}
+
+
+\renewcommand{\topfraction}{.85}
+\renewcommand{\bottomfraction}{.7}
+\renewcommand{\textfraction}{.15}
+\renewcommand{\floatpagefraction}{.5}
+\renewcommand{\dbltopfraction}{.66}
+\renewcommand{\dblfloatpagefraction}{.66}
+\setcounter{topnumber}{9}
+\setcounter{bottomnumber}{9}
+\setcounter{totalnumber}{20}
+\setcounter{dbltopnumber}{9}
+
+\makeindex
+
+\usepackage{multicol}
+\usepackage[rgb,x11names]{xcolor}% Optimize for screen reading.
+\usepackage{hyperxmp}
+\usepackage{hyperref}
+\hypersetup{
+ pdftitle={MetaPost: A User's Manual},
+ pdfauthor={John D. Hobby and the MetaPost development team},
+ pdfkeywords={MetaPost, PostScript, SVG, PNG, vector graphics language,
+ MetaFont, TeX}
+}
+\hypersetup{
+ pdfstartview={XYZ null null null},% Zoom factor is determined by viewer.
+ colorlinks,
+ linkcolor=RoyalBlue3,
+ urlcolor=Chocolate4,
+ citecolor=SpringGreen3
+}
+\usepackage[all]{hypcap}
+\ifpdf
+\pdfmapfile{=cm2lm.map}% replace CM by LM in figures
+\else
+\DeclareGraphicsExtensions{.mps}
+\DeclareGraphicsRule{mps}{eps}{*}{}
+\usepackage{breakurl}
+\fi
+\begin{document}
+\VerbatimFootnotes
+%%% Title page layout documentation is missing.
+\begin{titlepage}
+ \vbox to \textheight {%
+ \vskip0pt
+ \vfil
+ \vfil
+ \vfil
+ \centerline{\resizebox{3.5in}{!}{\fontseries{b}\selectfont\MP}}
+ \vskip10bp% actually 21bp (-11bp)
+ \centerline{\includegraphics{mpman-60.mps}}
+ \vskip15bp% actually 21bp (-6bp)
+ \centerline{%
+ \resizebox{3.5in}{!}{%
+ \scshape%
+ \fontsize{28bp}{28bp}\selectfont
+ \strut\lowercase{A USER\kern-2bp\lower3bp\hbox{'}S MANUAL}%
+ }%
+ }
+ \vskip-11bp
+ \vfil
+ \vfil
+ \centerline{\large John D. Hobby}
+ \vskip3bp
+ \centerline{and the MetaPost development team}
+ \vskip20.8bp% actually 31.8bp (-11bp)
+ \centerline{\large documented version: \mpversion}
+ \vskip3bp
+\tracingall \centerline{\svnInfoMaxToday} \tracingnone
+ \vskip\baselineskip
+ \centerline{Web page: {\tt https://tug.org/metapost}}
+ \centerline{Mailing list: {\tt https://lists.tug.org/metapost}}
+ \vfil
+ \vfil
+ }
+\end{titlepage}
+
+\setlength{\columnsep}{2.5em}
+\begin{multicols}{2}
+\tableofcontents
+\end{multicols}
+
+\section{Introduction}
+\label{intro}
+
+MetaPost is a programming language much like Knuth's \MF\footnote{\MF\
+is a trademark of Addison Wesley Publishing
+company.}\index{metafont?\MF}~\cite{kn:c} except that it outputs
+either vector graphics in the Postscript or SVG formats or bitmap
+graphics in the PNG format. Borrowed from \MF\ are the basic tools for
+creating and manipulating pictures. These include numbers, coordinate
+pairs, cubic splines, affine transformations, text strings, and boolean
+quantities. Additional features facilitate integrating text and
+graphics and accessing special features of
+PostScript\footnote{PostScript is a trademark of Adobe Systems
+Inc.}\index{PostScript} such as clipping, shading, and dashed lines.
+Another feature borrowed from \MF\ is the ability to solve linear
+equations that are given implicitly, thus allowing many programs to be
+written in a largely declarative style. By building complex operations
+from simpler ones, MetaPost achieves both power and flexibility.
+
+MetaPost is particularly well-suited to generating figures for technical
+documents where some aspects of a picture may be controlled by
+mathematical or geometrical constraints that are best expressed
+symbolically. In other words, MetaPost is not meant to take the place
+of a freehand drawing tool or even an interactive graphics editor. It
+is really a programming language for generating graphics, especially
+figures for \TeX\footnote{\TeX\ is a trademark of the American
+Mathematical Society.}\index{TeX?\TeX} and troff\index{troff} documents.
+
+This document introduces the MetaPost language, beginning with the
+features that are easiest to use and most important for simple
+applications. The first few sections describe the language as it
+appears to the novice user with key parameters at their default values.
+Some features described in these sections are part of a predefined macro
+package called Plain. Later sections summarize the complete language
+and distinguish between primitives and preloaded macros from the Plain
+macro package\index{Plain macros}. Reading the manual and creating
+moderately complex graphics with MetaPost does not require knowledge of
+\MF\ or access to {\sl The \MF book} \cite{kn:c}. However, to really
+master MetaPost, both are beneficial, since the MetaPost language is
+based on Knuth's \MF\ to a large extent. Appendix~\ref{MPvsMF} gives a
+detailed comparison of MetaPost and \MF.
+
+The basic MetaPost documentation is completed with ``Drawing Boxes with
+MetaPost'' and ``Drawing Graphs with MetaPost''---the manuals of the
+\texttt{boxes} and \texttt{graph} packages originally developed by
+John~D. Hobby.
+
+The MetaPost home page is \url{https://tug.org/metapost}. It has links
+to much additional information, including many articles that have been
+written about MetaPost. For general help and discussion, try the
+\url{metapost@tug.org} mailing list; you can subscribe to this list at
+\url{https://lists.tug.org/metapost}.
+
+The development repository is currently hosted at
+\url{https://serveur-svn.lri.fr/svn/modhel/metapost}; web browsing and
+anonymous svn checkout are allowed with username \texttt{anonsvn} and
+password \texttt{anonsvn}.
+
+If bug reports get no reply from \url{metapost@tug.org}, feel free to
+resend to \url{mp-implementors@tug.org}. (Please do not send reports
+directly to Dr.~Hobby in any event.)
+
+
+\section{Basic Drawing Statements}
+\label{basic}
+
+The simplest drawing statement is the one that draws a single dot with
+the current pen at a given coordinate:
+$$
+\begin{verbatim}
+drawdot (30,0)
+\end{verbatim}
+\index{drawdot?\texttt{drawdot}}
+\label{Ddrawdot}
+$$
+
+MetaPost can also draw straight lines.
+Thus\index{draw?\texttt{draw}}\index{-{}-?\texttt{-{}-}}
+$$ \hbox{\verb|draw (20,20)--(0,0)|} $$
+draws\index{draw?\texttt{draw}} a diagonal line and
+$$ \hbox{\verb|draw (20,20)--(0,0)--(0,30)--(30,0)--(0,0)|} $$
+draws a polygonal line like this:
+$$ \includegraphics{mpman-1.mps} $$
+
+What is meant by coordinates like \verb|(30,0)|? MetaPost uses the same
+default coordinate system that PostScript\index{PostScript!coordinate
+system} does. This
+means that \verb|(30,0)| is 30 units to the right of the origin, where a
+unit is $1\over72$ of an inch. We shall refer to this default unit as a
+{\sl PostScript point\/}\index{PostScript!point}\index{point!PostScript}
+to distinguish it from the standard printer's
+point\index{point!printer's} which is $1\over72.27$ inches.
+
+MetaPost uses the same names for units of measure that \TeX\ and \MF\
+do. Thus
+\verb|bp|\index{bp?\texttt{bp}}\index{units!bp?\texttt{bp}}\label{Dbp}
+refers to PostScript points (``big points'') and
+\verb|pt|\index{pt?\texttt{pt}}\index{units!pt?\texttt{pt}}\label{Dpt}
+refers to printer's points. Other units of measure include
+\verb|in|\index{in?\texttt{in}}\index{units!in?\texttt{in}}\label{Din}
+for inches,
+\verb|pc|\index{pc?\texttt{pc}}\index{units!pc?\texttt{pc}}\label{Dpc}
+for picas,
+\verb|cm|\index{cm?\texttt{cm}}\index{units!cm?\texttt{cm}}\label{Dcm}
+for centimeters,
+\verb|mm|\index{mm?\texttt{mm}}\index{units!mm?\texttt{mm}}\label{Dmm}
+for millimeters,
+\verb|cc|\index{cc?\texttt{cc}}\index{units!cc?\texttt{cc}}\label{Dcc}
+for ciceros, and
+\verb|dd|\index{dd?\texttt{dd}}\index{units!dd?\texttt{dd}}\label{Ddd}
+for Didot points. For example,
+$$ \hbox{\verb|(2cm,2cm)--(0,0)--(0,3cm)--(3cm,0)--(0,0)|} $$
+generates a larger version of the above diagram. It is OK to say
+\verb|0| instead \verb|0cm| because {\tt cm} is really just a conversion
+factor and {\tt 0cm} just multiplies the conversion factor by zero.
+(MetaPost understands constructions like {\tt 2cm}\index{multiplication,
+ implicit} as shorthand for \verb|2*cm|). The coordinate \verb|(0,0)|
+can also be referred to as
+\texttt{origin}\index{origin?\texttt{origin}}\label{Dorigin}, as in
+$$ \hbox{\verb|drawdot origin|} $$
+
+It is convenient to introduce your own scale factor, say $u$. Then you
+can define coordinates in terms of $u$ and decide later whether you want
+to begin with \verb|u=1cm| or \verb|u=0.5cm|. This gives you control
+over what gets scaled and what does not so that changing $u$ will not
+affect features such as line widths.
+
+There are many ways to affect the appearance of a line besides just
+changing its width, so the width-control mechanisms allow a lot of
+generality that we do not need yet. This leads to the strange looking
+statement\index{pickup?\texttt{pickup}}\index{pencircle?\texttt{pencircle}}%
+\index{scaled?\texttt{scaled}}
+$$ \hbox{\verb|pickup pencircle scaled 4pt|} $$
+for setting the line width (actually the pen size) for subsequent
+\verb|draw| or \verb|drawdot| statements to 4 points. (This is about
+eight times the default pen size).
+
+With such a large pen size, the \verb|drawdot| statement draws rather
+bold dots. We can use this to make a grid of dots by nesting
+\verb|drawdot| in a pair of loops:\index{loops}%
+$$
+\begin{verbatim}
+for i=0 upto 2:
+ for j=0 upto 2: drawdot (i*u,j*u); endfor
+endfor
+\end{verbatim}
+\index{for?\texttt{for}}
+\index{endfor?\texttt{endfor}}
+$$
+The outer loop runs for $i=0,1,2$ and the inner loop runs for $j=0,1,2$.
+The result is a three-by-three grid of bold dots as shown in Figure~\ref{fig1}.
+The figure also includes a larger version of the polygonal line diagram that we
+saw before.
+
+\begin{figure}[htp]
+$$ \begin{verbatim}
+beginfig(2);
+u=1cm;
+draw (2u,2u)--(0,0)--(0,3u)--(3u,0)--(0,0);
+pickup pencircle scaled 4pt;
+for i=0 upto 2:
+ for j=0 upto 2: drawdot (i*u,j*u); endfor
+endfor
+endfig;
+\end{verbatim}
+\quad \mathcenter{\includegraphics{mpman-2.mps}}
+$$
+\caption{MetaPost commands and the resulting output}
+\label{fig1}
+\end{figure}
+
+
+\section{The MetaPost Workflow}
+\label{workflow}
+
+Before describing the MetaPost language in detail, let's have a look at
+MetaPost's graphic design workflow. This section also contains a few
+technical details about MetaPost's compilation process, just enough to
+get you started. Section~\ref{workflow2} is more elaborate on this
+topic.
+
+In this manual, we'll assume a stand-alone command-line executable of
+the MetaPost compiler is used, which is usually called
+\texttt{mpost}\index{mpost?\texttt{mpost}}. The syntax and program name
+itself are system-dependent; sometimes it is named \texttt{mp}. The
+executable is actually a small wrapper program around
+\emph{mplib}\index{mplib?\emph{mplib}}, a library containing the
+MetaPost compiler. The library can as well be embedded into third-party
+applications.\footnote{C~API\index{mplib?\emph{mplib}!C~API} and Lua
+ bindings\index{mplib?\emph{mplib}!Lua bindings} are described in file
+ \verb|manual/mplibapi.pdf|\index{mplib?\emph{mplib}!mplibapi.pdf?\texttt{mplibapi.pdf}}
+ as part of the MetaPost distribution.} Section~\ref{mpimport} has
+some brief information on how to use the MetaPost compiler built-into
+Lua\TeX. For more information, please refer to the documentation of the
+embedding application.
+
+The basic MetaPost workflow\index{workflow} is depicted in
+figure~\ref{fig:mpworkflow}. Being a graphics description language,
+creating graphics with MetaPost follows the
+\emph{edit-compile-debug}\index{edit}\index{compile}\index{debug}
+paradigm known from other programming languages.
+
+\begin{figure}[tbp]
+$$ \includegraphics{mpman-charts-2.mps} $$
+\caption{The basic MetaPost workflow}
+\label{fig:mpworkflow}
+\end{figure}
+
+To create graphics with MetaPost, you prepare\index{edit} a text file
+containing code in the MetaPost language and then invoke the
+compiler\index{compile}, usually by giving a command of the form
+$$
+\begin{verbatim}[commandchars=\\\{\}]
+mpost \tdescr{input file}
+\end{verbatim}
+\index{mpost?\texttt{mpost}}
+$$
+on the command-line. MetaPost input files\index{files!input} normally
+have names ending \texttt{.mp}\index{mp file?{\tt mp}
+ file}\index{files!mp?{\tt mp}} but this part of the name can be
+omitted when invoking MetaPost. A complete description of the
+command-line syntax can be found in Section~\ref{refman:commandline}.
+
+Any terminal I/O during the compilation process is summarized in a
+transcript\index{files!transcript}\index{transcript file|see{files,
+ transcript}} file called \texttt{\tdescr{jobname}.log}\index{log
+ file?{\tt log} file}\index{files!log?{\tt log}}, where
+\tdescr{jobname} is the base name of the input file. This includes
+error messages and any MetaPost commands entered in interactive mode.
+
+If all goes well during compilation, MetaPost outputs one or more
+graphic files in a variant of the PostScript format, by default.
+PostScript output can be previewed\index{preview} with any decent
+PostScript viewer, e.g., GSview\index{GSview} or
+PS\_View\index{PSView?PS\_View}. Section~\ref{preview} has some tips
+and discusses several more elaborate ways for previewing PostScript
+output. Particularly, if graphics contain text labels, some more work
+might be required to get robust results in a PostScript viewer.
+MetaPost is also capable of generating graphics in the SVG\index{SVG}
+and PNG\index{PNG} formats. These file types can be previewed with
+certain web browsers, for example Firefox~3\index{Firefox} or
+Konqueror~4.2\index{Konqueror}, or general purpose image viewers.
+
+What does one do with all the graphic files? PostScript files are
+perfectly suitable for inclusion into documents created by
+\TeX\index{TeX?\TeX} or troff\index{troff}. The SVG format, as an XML
+descendant (Extensible Meta Language), is more aiming at automated data
+processing/interchanging. The PNG format is a losslessly compressing
+bitmap format. Both, SVG and PNG graphics, are widely used for web
+applications. Section~\ref{mpimport} deals with the import of MetaPost
+graphics into external applications.
+
+A MetaPost input file\index{files!input}\index{edit}\index{edit}
+normally contains a sequence of
+\verb|beginfig()|\index{beginfig?\texttt{beginfig}},
+\verb|endfig|\index{endfig?\texttt{endfig}} pairs with an
+\verb|end|\index{end?\texttt{end}} statement after the last
+one.\footnote{Omitting the final \verb|end| statement causes MetaPost to
+ enter interactive mode\index{interactive mode} after processing the
+ input file.} These are macros that perform various administrative
+functions and ensure that the results of all drawing operations get
+packaged up and translated into PostScript (or the SVG or PNG format).
+The numeric argument to the \verb|beginfig| macro determines the name of
+the corresponding output file, whose name, by default, is of the form
+\texttt{\tdescr{jobname}.\tdescr{n}}, where \tdescr{n} is the current
+argument to \verb|beginfig| rounded to the nearest integer. As an
+example, if a file is named \texttt{fig.mp} and contains the lines
+$$
+\begin{verbatim}[commandchars=\\\{\}]
+beginfig(1);
+ \tdescr{drawing statements}
+endfig;
+end
+\end{verbatim}
+$$
+the output from statements between \verb|beginfig(1)| and the next
+\verb|endfig| is written in a file \texttt{fig.1}\index{files!output}.
+
+Statements can also appear outside \verb|beginfig| \ldots\
+\verb|endfig|. Such statements are processed, but drawing operations
+generate no visible output. Typically, global configurations are put
+outside \verb|beginfig| \ldots\ \verb|endfig|, e.g., assignments to
+internal variables, such as \texttt{outputtemplate}, or a \LaTeX\
+preamble declaration for enhanced text rendering.
+Comments\index{comments} in MetaPost code are introduced by the percent
+sign~\verb|%|\index{\%?\texttt{\%}!comment}, which causes the remainder
+of the current line to be ignored.
+
+The remainder of this section briefly introduces three assignments to
+internal variables, each one useful by itself, that can often be found
+in MetaPost input files:
+$$
+\begin{verbatim}[commandchars=\\\{\}]
+prologues := 3; \smallskip
+outputtemplate := "%j-%c.mps"; \smallskip
+outputformat := "svg";
+\end{verbatim}
+$$
+
+If your graphics contain text labels, you might want to set variable
+\texttt{prologues} to~3 to make sure the correct fonts are used under
+all possible circumstances. The second assignment changes the output
+file naming scheme to the form \texttt{\tdescr{jobname}-\tdescr{n}.mps}.
+That way, instead of a numeric index, all output files get a uniform
+file extension \texttt{mps}\index{mps file?{\tt mps}
+ file}\index{files!mps?{\tt mps}}, which is typically used for
+MetaPost's PostScript output. The last assignment lets MetaPost write
+output files in the SVG format rather than in the PostScript format.
+More information can be found in Sections~\ref{Dprologues}
+and~\ref{workflow2}.
+
+
+\section{Curves}
+\label{curves}
+
+MetaPost is perfectly happy to draw curved lines as well as straight ones.
+A \verb|draw| statement with the points separated by
+\verb|..|\index{..?\texttt{..}} draws a smooth curve through the points.
+For example consider the result of
+$$ \hbox{\verb|draw z0..z1..z2..z3..z4|} $$
+after defining five points as follows:
+$$\begin{verbatim}
+z0 = (0,0); z1 = (60,40);
+z2 = (40,90); z3 = (10,70);
+z4 = (30,50);
+\end{verbatim}
+$$
+Figure~\ref{fig2} shows the curve with points \verb|z0| through \verb|z4|
+labeled.
+
+\begin{figure}[htp]
+$$ \includegraphics{mpman-3.mps}
+$$
+\caption[A curve through points 0, 1, 2, 3, and 4]
+ {The result of {\tt draw z0..z1..z2..z3..z4}}
+\label{fig2}
+\end{figure}
+
+There are many other ways to draw a curved path through the same five
+points. To make a smooth closed curve, connect \verb|z4| back to the
+beginning by appending \verb|..cycle|\index{cycle?\texttt{cycle}} to the
+\verb|draw| statement as shown in Figure~\ref{fig3}a. It is also
+possible in a single \verb|draw| statement to mix curves and straight
+lines as shown in Figure~\ref{fig3}b. Just use \verb|--| where you want
+straight lines and \verb|..| where you want curves. Thus
+$$ \hbox{\verb|draw z0..z1..z2..z3--z4--cycle|} $$
+produces a curve through points 0,~1, 2, and~3, then a polygonal line from
+point~3 to point~4 and back to point~0. The result is essentially the same
+as having two draw statements
+\begin{eqnarray*}
+ \hbox{\verb|draw z0..z1..z2..z3|}\\
+\noalign{\hbox{and}}
+ \hbox{\verb|draw z3--z4--z0|}
+\end{eqnarray*}
+
+\begin{figure}[htp]
+$$ {\includegraphics{mpman-104.mps} \atop (a)}
+ \qquad {\includegraphics{mpman-204.mps} \atop (b)}
+$$
+\caption[Closed curves through five points]
+ {(a)~The result of {\tt draw z0..\linebreak[0]z1..\linebreak[0]%
+ z2..\linebreak[0]z3..\linebreak[0]z4..\linebreak[0]cycle};
+ (b)~the result of {\tt draw z0..\linebreak[0]z1..\linebreak[0]%
+ z2..\linebreak[0]z3--\linebreak[0]z4--\linebreak[0]cycle}.}
+\label{fig3}
+\end{figure}
+
+MetaPost already provides a small selection of basic path shapes that
+can be used to derive custom paths from. The predefined variable
+\texttt{fullcircle}\index{fullcircle?\texttt{fullcircle}}\label{Dfcirc}
+refers to a closed path describing a circle of unit diameter centered on
+the origin. There are also
+\texttt{halfcircle}\index{halfcircle?\texttt{halfcircle}}\label{Dhcirc}
+and
+\texttt{quartercircle}\index{quartercircle?\texttt{quartercircle}}\label{Dqcirc},
+the former being the part of a full circle covering the first and second
+quadrant and the latter covering just the first quadrant. Because of
+the mathematical model that is used to describe paths in MetaPost, all
+these are not exactly circular paths, but very good approximations (see
+Figure~\ref{fig3a}).
+
+\begin{figure}
+$$ \includegraphics{mpman-61.mps} $$
+\caption{A circle and a square with cardinal points. Arrows are
+ pointing to the start and end points of the closed paths.}
+\label{fig3a}
+\end{figure}
+
+Rectangularly shaped paths can be derived from
+\texttt{unitsquare}\index{unitsquare?\texttt{unitsquare}}\label{Dunitsqr},
+a closed path describing a square of unit side length whose lower left
+corner is located at the origin.
+
+\subsection{B\'ezier Cubic Curves}
+
+When MetaPost is asked to draw a smooth curve through a sequence of
+points, it constructs a piecewise cubic curve with continuous slope and
+approximately continuous curvature\index{curvature}. This means that a
+path specification such as
+$$ \hbox{\verb|z0..z1..z2..z3..z4..z5|} $$
+results in a curve that can be defined parametrically\index{parameterization}
+as $(X(t),Y(t))$ for
+$0\le t\le5$, where $X(t)$ and $Y(t)$ are piecewise cubic functions. That is,
+there is a different pair of cubic functions for each integer-bounded
+$t$-interval. If ${\tt z0}=(x_0,y_0)$, ${\tt z1}=(x_1,y_1)$,
+${\tt z2}=(x_2,y_2)$, \ldots, MetaPost selects
+B\'ezier control\index{control points} points
+$(x_0^+,y_0^+)$, $(x_1^-,y_1^-)$, $(x_1^+,y_1^+)$, \ldots, where
+\begin{eqnarray*}
+ X(t+i) &=& (1-t)^3x_i + 3t(1-t)^2x_i^+ + 3t^2(1-t)x_{i+1}^- + t^3x_{i+1},\\
+ Y(t+i) &=& (1-t)^3y_i + 3t(1-t)^2y_i^+ + 3t^2(1-t)y_{i+1}^- + t^3y_{i+1}
+\end{eqnarray*}
+for $0\le t\le1$. The precise rules for choosing the B\'ezier control points
+are described in \cite{ho:splin} and in {\sl The \MF book\/}~\cite{kn:c}.
+
+In order for the path to have a continuous slope at $(x_i,y_i)$, the incoming
+and outgoing directions at $(X(i),Y(i))$ must match. Thus the vectors
+$$ (x_i-x_i^-,\,y_i-y_i^-) \qquad \hbox{and}
+ \qquad (x_i^+-x_i,\,y_i^+-y_i)
+$$
+must have the same direction; i.e., $(x_i,y_i)$ must be on the line segment
+between $(x_i^-,y_i^-)$ and $(x_i^+,y_i^+)$. This situation is illustrated
+in Figure~\ref{fig4} where the B\'ezier control points selected by MetaPost
+are connected by dashed lines. For those who are familiar with the interesting
+properties of this construction, MetaPost allows the control points to be
+specified directly in the following format:\index{controls?\texttt{controls}}
+$$ \begin{verbatim}
+draw (0,0)..controls (26.8,-1.8) and (51.4,14.6)
+ ..(60,40)..controls (67.1,61.0) and (59.8,84.6)
+ ..(40,90)..controls (25.4,94.0) and (10.5,84.5)
+ ..(10,70)..controls ( 9.6,58.8) and (18.8,49.6)
+ ..(30,50);
+\end{verbatim}
+$$
+
+For a way to extract the control points of a path, given by the user or
+calculated by MetaPost, see section~\ref{Dprepostctrl}.
+
+\begin{figure}[htp]
+$$ \includegraphics{mpman-5.mps}
+$$
+\caption[A curve and the control polygon]
+ {The result of {\tt draw z0..z1..z2..z3..z4} with the
+ automatically-selected B\'ezier control polygon illustrated by dashed
+ lines.}
+\label{fig4}
+\end{figure}
+
+\subsection{Specifying Direction, Tension, and Curl}
+\label{tenscurl}
+
+MetaPost provides many ways of controlling the behavior of a curved path
+without actually specifying the control points. For instance, some
+points on the path may be selected as vertical or horizontal extrema.
+If \verb|z1| is to be a horizontal extreme and \verb|z2| is to be a
+vertical extreme, you can specify that $(X(t),Y(t))$ should go upward at
+\verb|z1| and to the left at \verb|z2|:
+$$ \hbox{\verb|draw z0..z1{up}..z2{left}..z3..z4;|} $$
+The resulting shown in Figure~\ref{fig5} has the desired vertical and
+horizontal directions at \verb|z1| and \verb|z2|, but it does not look
+as smooth as the curve in Figure~\ref{fig2}. The reason is the large
+discontinuity in curvature\index{curvature} at \verb|z1|. If it were
+not for the specified direction at \verb|z1|, the MetaPost interpreter
+would have chosen a direction designed to make the curvature above
+\verb|z1| almost the same as the curvature below that point.
+
+\begin{figure}[htp]
+$$ \includegraphics{mpman-6.mps}
+$$
+\caption[A curve and the control polygon]
+ {The result of {\tt draw z0..z1\char`\{up\char`\}..z2\char`\{left\char`\}%
+ ..z3..z4}.}
+\label{fig5}
+\end{figure}
+
+How can the choice of directions at given points on a curve determine whether
+the curvature will be continuous? The reason is that curves used in MetaPost
+come from a family where a path is determined by its endpoints and the
+directions there. Figures \ref{fig6} and~\ref{fig7} give a good idea of what
+this family of curves is like.
+
+\begin{figure}[htp]
+$$ \mathcenter{\includegraphics{mpman-7.mps}} \quad
+\begin{verbatim}
+beginfig(7)
+for a=0 upto 9:
+ draw (0,0){dir 45}..{dir -10a}(6cm,0);
+endfor
+endfig;
+\end{verbatim}
+$$
+\caption{A curve family and the MetaPost instructions for generating it}
+\label{fig6}
+\end{figure}
+
+\begin{figure}[htp]
+$$ \mathcenter{\includegraphics{mpman-8.mps}} \quad
+\begin{verbatim}
+beginfig(8)
+for a=0 upto 7:
+ draw (0,0){dir 45}..{dir 10a}(6cm,0);
+endfor
+endfig;
+\end{verbatim}
+$$
+\caption{Another curve family with the corresponding MetaPost instructions}
+\label{fig7}
+\end{figure}
+
+Figures \ref{fig6} and~\ref{fig7} illustrate a few new MetaPost
+features. The first is the {\tt
+dir}\index{dir?\texttt{dir}}\label{Ddirop} operator that takes an angle
+in degrees and generates a unit vector in that direction. Thus
+\verb|dir 0| is equivalent to {\tt
+right}\index{right?\texttt{right}}\label{Dright} and \verb|dir 90| is
+equivalent to {\tt up}\index{up?\texttt{up}}\label{Dup}. There are also
+predefined direction vectors {\tt
+left}\index{left?\texttt{left}}\label{Dleft} and {\tt
+down}\index{down?\texttt{down}}\label{Ddown} for {\tt dir 180} and {\tt
+dir 270}.
+
+The direction
+vectors given in \verb|{}| can be of any length, and they can come before a
+point as well as after one. It is even possible for a path specification
+to have directions given before and after a point. For example a path
+specification containing
+$$ \hbox{\verb|..{dir 60}(10,0){up}..|} $$
+produces a curve with a corner at $(10,0)$.
+
+Note that some of the curves in Figure~\ref{fig6} have points of
+inflection\index{inflections}. This is necessary in order to produce
+smooth curves in situations like Figure~\ref{fig3}a, but it is probably
+not desirable when dealing with vertical and horizontal extreme points
+as in Figure~\ref{fig8}a. If \verb|z1| is supposed to be the topmost
+point on the curve, this can be achieved by using
+\verb|...|\index{...?\texttt{...}} instead of \verb|..| in the path
+specification as shown in Figure~\ref{fig8}b. The meaning of \verb|...|
+is ``choose an inflection-free path between these points unless the
+endpoint directions make this impossible.'' (It would be possible to
+avoid inflections in Figure~\ref{fig6}, but not in Figure~\ref{fig7}).
+
+\begin{figure}[htp]
+$$ {\mathcenter{\includegraphics{mpman-109.mps}} \atop
+ \hbox{\verb|draw z0{up}..z1{right}..z2{down}|}}
+ \quad
+ {\mathcenter{\includegraphics{mpman-209.mps}} \atop
+ \hbox{\verb|draw z0{up}...z1{right}...z2{down}|}}
+$$
+\caption{Two {\tt draw} statements and the resulting curves.}
+\label{fig8}
+\end{figure}
+
+Another way to control a misbehaving path is to increase the
+``tension''\index{tension} parameter. Using \verb|..| in a path
+specification sets the tension parameter to the default value~1. If
+this makes some part of a path a little too wild, we can selectively
+increase the tension. If Figure~\ref{fig9}a is considered ``too wild,''
+a {\tt draw} statement of the following form increases the tension
+between {\tt z1} and {\tt z2}:
+$$ \hbox{\verb|draw z0..z1..tension 1.3..z2..z3|} $$
+This produces Figure~\ref{fig9}b. For an asymmetrical effect like
+Figure~\ref{fig9}c, the \verb|draw| statement becomes
+$$ \hbox{\verb|draw z0..z1..tension 1.5 and 1..z2..z3|} $$
+The tension parameter can be less than one, but it must be at least $3\over4$.
+
+\begin{figure}[htp]
+$$ {\mathcenter{\includegraphics{mpman-110.mps}} \atop (a)}
+ \quad
+ {\mathcenter{\includegraphics{mpman-210.mps}} \atop (b)}
+ \quad
+ {\mathcenter{\includegraphics{mpman-310.mps}} \atop (c)}
+$$
+\caption[Effects of changing the tension parameter]
+ {Results of {\tt draw z0..z1..tension} $\alpha$ {\tt and} $\beta$
+ {\tt ..z2..z3} for various $\alpha$ and $\beta$:
+ (a)~$\alpha=\beta=1$; (b)~$\alpha=\beta=1.3$;
+ (c)~$\alpha=1.5$, $\beta=1$.}
+\label{fig9}
+\end{figure}
+
+MetaPost paths also have a parameter called
+``curl''\index{curl?\texttt{curl}} that affects the ends of a path. In
+the absence of any direction specifications, the first and last segments
+of a non-cyclic path are approximately circular arcs as in the $c=1$
+case of Figure~\ref{fig10}. To use a different value for the curl
+parameter, specify \verb|{curl c}| for some other value of $c$. Thus
+$$ \hbox{\verb|draw z0{curl c}..z1..{curl c}z2|} $$
+sets the curl parameter for \verb|z0| and \verb|z2|. Small values of
+the curl parameter reduce the curvature\index{curvature} at the
+indicated path endpoints, while large values increase the curvature as
+shown in Figure~\ref{fig10}. In particular, a curl value of zero makes
+the curvature approach zero.
+
+\begin{figure}[htp]
+$$ {\mathcenter{\includegraphics{mpman-111.mps}} \atop c=0}
+ \qquad
+ {\mathcenter{\includegraphics{mpman-211.mps}} \atop c=1}
+ \qquad
+ {\mathcenter{\includegraphics{mpman-311.mps}} \atop c=2}
+ \qquad
+ {\mathcenter{\includegraphics{mpman-411.mps}} \atop c=\infty}
+$$
+\caption[Effects of changing the curl parameter]
+ {Results of {\tt draw z0\char`\{curl c\char`\}..z1..%
+ \char`\{curl c\char`\}z2} for various values
+ of the curl parameter~$c$.}
+\label{fig10}
+\end{figure}
+
+\subsection{Summary of Path Syntax}
+
+There are a few other features of MetaPost path syntax, but they are
+relatively unimportant. Since \MF\ uses the same path syntax,
+interested readers can refer to \cite[chapter 14]{kn:c}. The summary of
+path syntax in Figure~\ref{sypath} includes everything discussed so far
+including the \verb|--| and \verb|...| constructions which \cite{kn:c}
+shows to be macros rather than primitives. A few comments on the
+semantics are in order here: If there is a non-empty $\descr{direction
+specifier}$ before a $\descr{path knot}$ but not after it, or vice
+versa, the specified direction (or curl amount) applies to both the
+incoming and outgoing path segments. A similar arrangement applies when
+a $\descr{controls}$ specification gives only one $\descr{pair
+primary}$. Thus
+$$ \hbox{\verb|..controls (30,20)..|} $$
+is equivalent to
+$$ \hbox{\verb|...controls (30,20) and (30,20)..|} $$
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\descr{path expression} \rightarrow
+ \descr{path subexpression}$\\
+\qquad \= ${}\mid \descr{path subexpression} \descr{direction specifier}$\\
+\> ${}\mid \descr{path subexpression} \descr{path join}$ \verb|cycle|\\
+$\descr{path subexpression} \rightarrow
+ \descr{path knot}$\\
+\> ${}\mid \descr{path expression} \descr{path join} \descr{path knot}$\\
+$\descr{path join} \rightarrow
+ \hbox{\verb|--|}$\\
+\> ${}\mid \descr{direction specifier} \descr{basic path join}
+ \descr{direction specifier}$\\
+$\descr{direction specifier} \rightarrow
+ \descr{empty}$\\
+\> ${}\mid {}$\verb|{curl| $\descr{numeric expression}$\verb|}|\\
+\> ${}\mid {}$\verb|{|$\descr{pair expression}$\verb|}|\\
+\> ${}\mid {}$\verb|{|$\descr{numeric expression}$\verb|,|%
+ $\descr{numeric expression}$\verb|}|\\
+$\descr{basic path join} \rightarrow
+ \hbox{\verb|..|}
+ \mid \hbox{\verb|...|}
+ \mid \hbox{\verb|..|}\descr{tension}\hbox{\verb|..|}
+ \mid \hbox{\verb|..|}\descr{controls}\hbox{\verb|..|}$\\
+$\descr{tension} \rightarrow
+ \hbox{\verb|tension|}\descr{numeric primary}$\\
+\> ${}\mid \hbox{\verb|tension|}\descr{numeric primary}
+ \hbox{\verb|and|}\descr{numeric primary}$\\
+$\descr{controls} \rightarrow
+ \hbox{\verb|controls|}\descr{pair primary}$\\
+\> ${}\mid \hbox{\verb|controls|}\descr{pair primary}
+ \hbox{\verb|and|}\descr{pair primary}$
+\end{ctabbing}
+\caption{The syntax for path construction}
+\label{sypath}
+\end{figure}
+
+A pair of coordinates like \verb|(30,20)| or a \verb|z| variable that
+represents a coordinate pair is what Figure~\ref{sypath} calls a
+$\descr{pair primary}$. A $\descr{path knot}$ is similar except that it
+can take on other forms such as a path expression in parentheses.
+Primaries and expressions of various types will be discussed in full
+generality in Section~\ref{exprs}.
+
+
+\section{Linear Equations}
+\label{lin.eq}
+
+An important feature taken from \MF\ is the ability to solve linear
+equations so that programs can be written in a partially declarative fashion.
+For example, the MetaPost interpreter can read
+$$ \hbox{\verb|a+b=3; 2a=b+3;|} $$
+and deduce that $a=2$ and $b=1$. The same equations can be written
+slightly more compactly by stringing them together with multiple equal
+signs:
+$$ \hbox{\verb|a+b = 2a-b = 3;|} $$
+Whichever way you give the equations, you can then give the
+command\index{show?\texttt{show}}
+$$ \hbox{\tt show a,b;} $$
+to see the values of {\tt a} and {\tt b}. MetaPost responds by typing
+$$\begin{verbatim}
+>> 2
+>> 1
+\end{verbatim}
+$$
+
+Note that {\tt =}\index{=?\texttt{=}} is not an assignment operator; it
+simply declares that the left-hand side equals the right-hand side.
+Thus {\tt a=a+1} produces an error message complaining about an
+``inconsistent equation\index{Inconsistent equation?\texttt{Inconsistent
+equation}}.'' The way to increase the value of {\tt a} is to use the
+assignment\index{assignment} operator {\tt :=}\index{:=?\texttt{:=}} as
+follows:
+$$ \hbox{\tt a:=a+1;} $$
+In other words, {\tt :=} is for changing existing values while {\tt =} is for
+giving linear equations to solve.
+
+There is no restriction against mixing equations and assignment
+operations as in the following example:
+$$ \hbox{\tt a = 2; b = a; a := 3; c = a;} $$
+After the first two equations set {\tt a} and~{\tt b} equal to 2, the
+assignment operation changes {\tt a} to~3 without affecting {\tt b}.
+The final value of {\tt c} is 3 since it is equated to the new value of
+{\tt a}. In general, an assignment operation is interpreted by first
+computing the new value, then eliminating the old value from all
+existing equations before actually assigning the new value.
+
+\subsection{Equations and Coordinate Pairs}
+
+MetaPost can also solve linear equations involving coordinate pairs. We have
+already seen many trivial examples of this in the form of equations like
+$$ \hbox{\verb|z1=(0,.2in)|} $$
+Each side of the equation must be formed by adding or subtracting
+coordinate pairs and multiplying or dividing them by known numeric
+quantities. Other ways of naming pair-valued variables will be
+discussed later, but the ${\tt z}\descr{number}$\index{z convention?{\tt
+z} convention} is convenient because it is an abbreviation for
+$$ \hbox{\tt (x}\descr{number} \hbox{\tt, y}\descr{number}\hbox{\tt)} $$
+This makes it possible to give values to \verb|z| variables by giving
+equations involving their coordinates. For instance, points {\tt z1},
+{\tt z2}, {\tt z3}, and~{\tt z6} in Figure~\ref{fig12} were initialized
+via the following equations:
+\begin{eqnarray*}
+ &&\hbox{\verb|z1=-z2=(.2in,0);|} \\
+ &&\hbox{\verb|x3=-x6=.3in;|} \\
+ &&\hbox{\verb|x3+y3=x6+y6=1.1in;|}
+\end{eqnarray*}
+Exactly the same points could be obtained by setting their values directly:
+$$ \begin{verbatim}
+z1=(.2in,0); z2=(-.2in,0);
+z3=(.3in,.8in); z6=(-.3in,1.4in);
+\end{verbatim}
+$$
+
+After reading the equations, the MetaPost interpreter knows the values
+of {\tt z1}, {\tt z2}, {\tt z3}, and~{\tt z6}. The next step in the
+construction of Figure~\ref{fig12} is to define points {\tt z4} and {\tt
+z5} equally spaced along the line from {\tt z3} to {\tt z6}. Since this
+operation comes up often, MetaPost has a special syntax for it. This
+mediation construction\index{mediation}\index{[]?\texttt{[]}!mediation}
+$$ \hbox{\verb|z4=1/3[z3,z6]|} $$
+means that {\tt z4} is $1\over3$ of the way from $z3$ to $z6$; i.e.,
+$$ {\tt z4}={\tt z3}+{1\over3}({\tt z6}-{\tt z3}). $$
+Similarly
+$$ \hbox{\verb|z5=2/3[z3,z6]|} $$
+makes {\tt z5} $2\over3$ of the way from $z3$ to $z6$.
+
+\begin{figure}[htp]
+$$ \begin{verbatim}
+beginfig(13);
+z1=-z2=(.2in,0);
+x3=-x6=.3in;
+x3+y3=x6+y6=1.1in;
+z4=1/3[z3,z6];
+z5=2/3[z3,z6];
+z20=whatever[z1,z3]=whatever[z2,z4];
+z30=whatever[z1,z4]=whatever[z2,z5];
+z40=whatever[z1,z5]=whatever[z2,z6];
+draw z1--z20--z2--z30--z1--z40--z2;
+pickup pencircle scaled 1pt;
+draw z1--z2;
+draw z3--z6;
+endfig;
+\end{verbatim}
+\quad \mathcenter{\includegraphics{mpman-13.mps}}
+$$
+\caption[MetaPost code and figure using linear equations]
+ {MetaPost commands and the resulting figure. Point labels have been
+ added to the figure for clarity.}
+\label{fig12}
+\end{figure}
+
+Mediation can also be used to say that some point is at an unknown
+position along the line between two known points. For instance, we
+could a introduce new variable {\tt aa} and write something like
+$$ \hbox{\verb|z20=aa[z1,z3];|} $$
+This says that {\tt z20} is some unknown fraction {\tt aa} of the way
+along the line between {\tt z1} and {\tt z3}. Another such equation
+involving a different line is sufficient to fix the value of {\tt z20}.
+To say that {\tt z20} is at the intersection of the {\tt z1}-{\tt z3}
+line and the {\tt z2}-{\tt z4} line, introduce another variable {\tt ab}
+and set
+$$ \hbox{\verb|z20=ab[z2,z4];|} $$
+This allows MetaPost to solve for {\tt x20}, {\tt y20}, {\tt aa}, and {\tt ab}.
+
+It is a little painful to keep thinking up new names like {\tt aa} and
+{\tt ab}. This can be avoided by using a special feature called {\tt
+whatever}\index{whatever?\texttt{whatever}}\label{Dwhatev}. This macro
+generates a new anonymous variable each time it appears. Thus the
+statement
+$$ \hbox{\verb|z20=whatever[z1,z3]=whatever[z2,z4]|} $$
+sets {\tt z20} as before, except it uses {\tt whatever} to generate two
+{\em different\/} anonymous variables instead of {\tt aa} and {\tt ab}.
+This is how Figure~\ref{fig12} sets {\tt z20}, {\tt z30}, and
+{\tt z40}.
+
+\subsection{Dealing with Unknowns}
+
+A system of equations such as those used in Figure~\ref{fig12} can be given in
+any order as long as all the equations are linear and all the variables can
+be determined before they are needed. This means that the equations
+\begin{eqnarray*}
+ && \hbox{\verb|z1=-z2=(.2in,0);|}\\
+ && \hbox{\verb|x3=-x6=.3in;|}\\
+ && \hbox{\verb|x3+y3=x6+y6=1.1in;|}\\
+ && \hbox{\verb|z4=1/3[z3,z6];|}\\
+ && \hbox{\verb|z5=2/3[z3,z6];|}
+\end{eqnarray*}
+suffice to determine {\tt z1} through {\tt z6}, no matter what order the
+equations are given in. On the other hand
+$$ \hbox{\verb|z20=whatever[z1,z3]|} $$
+is legal only when a known value has previously been specified for the difference
+${\tt z3}-{\tt z1}$, because the equation is equivalent
+to\index{mediation}
+$$ \hbox{\verb|z20 = z1 + whatever*(z3-z1)|} $$
+and the linearity requirement disallows multiplying unknown components
+of ${\tt z3}-{\tt z1}$ by the anonymous unknown result of {\tt
+whatever}. The general rule is that you cannot multiply two unknown
+quantities or divide by an unknown quantity, nor can an unknown quantity
+be used in a {\tt draw} statement. Since only linear equations are
+allowed, the MetaPost interpreter can easily solve the equations and
+keep track of what values are known.
+
+The most natural way to ensure that MetaPost can handle an expression like
+$$ \hbox{\verb|whatever[z1,z3]|} $$
+is to ensure that {\tt z1} and {\tt z3} are both known. However this is not
+actually required since MetaPost may be able to deduce a known value for
+${\tt z3}-{\tt z1}$ before either of {\tt z1} and {\tt z3} are known.
+For instance, MetaPost will accept the equations
+$$ \hbox{\verb|z3=z1+(.1in,.6in); z20=whatever[z1,z3];|} $$
+but it will not be able to determine any of the components of {\tt z1},
+{\tt z3}, or {\tt z20}.
+
+These equations do give partial information about {\tt z1}, {\tt z3},
+and {\tt z20}. A good way to see this is to give another equation such as
+$$ \hbox{\verb|x20-x1=(y20-y1)/6;|} $$
+This produces the error message ``{\tt ! Redundant
+equation}\index{Redundant equation?\texttt{Redundant equation}}.''
+MetaPost assumes that you are trying to tell it something new, so it
+will usually warn you when you give a redundant equation. If the new
+equation had been
+$$ \hbox{\verb|(x20-x1)-(y20-y1)/6=1in;|} $$
+the error message would have been\index{Inconsistent
+equation?\texttt{Inconsistent equation}}
+$$ \hbox{\verb|! Inconsistent equation (off by 71.99979).|} $$
+This error message illustrates
+roundoff\index{roundoff error} error in MetaPost's linear equation solving
+mechanism. Roundoff error
+is normally not a serious problem, but it is likely to cause trouble if you are
+trying to do something like find the intersection of two lines that are almost
+parallel.
+
+
+\section{Expressions}
+\label{exprs}
+
+It is now time for a more systematic view of the MetaPost language. We
+have seen that there are numeric quantities and coordinate pairs, and
+that these can be combined to specify paths for {\tt draw} statements.
+We have also seen how variables can be used in linear equations, but we
+have not discussed all the operations and data types that can be used in
+equations.
+
+It is possible to experiment with expressions involving any of the data types
+mentioned below by using the statement\index{show?\texttt{show}}\label{Dshow}
+$$ {\tt show}\, \descr{expression} $$
+to ask MetaPost to print a symbolic representation of the value of each
+expression. For known numeric values, each is printed on a new line
+preceded by ``\verb|>> |''. Other types of result are printed similarly,
+except that complicated values are sometimes not printed on standard
+output. This produces a reference to the transcript
+file\index{files!transcript} that looks like this:
+$$ \hbox{\verb|>> picture (see the transcript file)|} $$
+If you want to the full results of {\tt show} statements to be printed
+on your terminal, assign a positive value to the internal\index{internal
+variables} variable\index{variables!internal} {\tt
+tracingonline}\index{tracingonline?\texttt{tracingonline}}\label{Dtonline}.
+
+\subsection{Data Types}
+\label{datatypes}
+
+MetaPost actually has ten basic data types\index{types}: numeric, pair,
+path, transform, (rgb)color, cmykcolor, string, boolean, picture, and
+pen. Let us consider these one at a time beginning with the numeric
+type.
+
+Numeric\index{numeric type} quantities in MetaPost are represented in
+fixed point arithmetic\index{arithmetic} as integer multiples of
+$1\over65536$, the smallest positive value, which is also available as
+the predefined constant
+\texttt{epsilon}\index{epsilon?\texttt{epsilon}}\label{Depsilon}.\footnote{MetaPost
+ can also do arithmetic with higher and (almost) arbitrary precision.
+ See Appendix~\ref{hparith} for more information.} Numeric quantities
+must normally have absolute values less than 4096 but intermediate
+results can be eight times larger. This should not be a problem for
+distances or coordinate values since 4096 PostScript points is more than
+1.4~meters. If you need to work with numbers of magnitude 4096 or more,
+setting the internal variable
+\texttt{warningcheck}\index{warningcheck?\texttt{warningcheck}}\label{Dwarncheck}
+to zero suppresses the warning messages about large numeric quantities.
+
+The pair\index{pair type} type is represented as a pair of numeric
+quantities. We have seen that pairs are used to give coordinates in
+{\tt draw} statements. Pairs can be added, subtracted, used in
+mediation expressions, or multiplied or divided by numerics.
+
+Paths\index{path type} have already been discussed in the context of {\tt draw}
+statements, but
+that discussion did not mention that paths are first-class objects that can be
+stored and manipulated. A path represents a straight or curved line that is
+defined parametrically.
+
+Another data type represents an arbitrary affine
+transformation\index{transform type}. A {\em transform\/} can be any
+combination of rotating, scaling, slanting, and shifting. If ${\tt
+p}=(p_x,p_y)$ is a pair and {\tt T} is a
+transform,\index{transformed?\texttt{transformed}}
+$$ \hbox{\tt p transformed T} $$
+is a pair of the form
+$$ (t_x+t_{xx}p_x+t_{xy}p_y, t_y+t_{yx}p_x+t_{yy}p_y), $$
+where the six numeric quantities $(t_x,t_y,t_{xx},t_{xy},t_{yx},t_{yy})$
+determine {\tt T}. Transforms can also be applied to paths, pictures, pens,
+and transforms.
+
+The color\index{color type} type is like the pair type, except
+that it has three components instead of two and each component is
+normally between 0 and 1. Like pairs, colors can be added,
+subtracted, used in mediation expressions, or multiplied or divided
+by numerics. Colors can be specified in terms of the predefined
+constants \ttindex{black}\label{Dblack}, \ttindex{white}\label{Dwhite},
+\ttindex{red}\label{Dred}, \ttindex{green}\label{Dgreen},
+\ttindex{blue}\label{Dblue}, or the red, green, and
+blue components can be given explicitly. Black is {\tt (0,0,0)} and
+white is {\tt (1,1,1)}. A level of gray such as {\tt (.4,.4,.4)} can also be
+specified as {\tt 0.4white}. Although color typed variables may be
+any ordered triplet, when adding an object to a picture, MetaPost will
+convert its color by clipping each component between 0 and 1. For
+example, MetaPost will output the color (1,2,3) as (1,1,1).
+MetaPost solves linear equations involving
+colors the same way it does for pairs. The type `rgbcolor' is an alias of
+type `color'.
+
+The cmykcolor\index{cmykcolor type} type is similar
+to the color type except that it has four components instead of
+three. This type is used to specify colors by their cyan, magenta,
+yellow, and black components explicitly. Because CMYK colors deal with
+pigments instead of light rays, the color white would be expressed as
+{\tt (0,0,0,0)} and black as {\tt (0,0,0,1)}. In theory, the colors
+{\tt ($c$,$m$,$y$,1)} and {\tt (1,1,1,$k$)} should result in black for
+any values of $c$, $m$, $y$ and~$k$, too. But in practice, this is
+avoided since it is a waste of colored ink and can lead to
+unsatisfactory results.
+
+A string\index{string type} represents a sequence of characters.
+String constants\index{string constants} are given
+in double quotes \hbox{\verb|"like this"|}. String constants cannot contain
+double quotes or newlines, but there is a way to construct a string containing
+any sequence of eight-bit characters.
+
+\label{Dscantokens}
+Conversion from strings to other types, notably numeric, can be accomplished by
+the {\tt scantokens}\index{scantokens?\texttt{scantokens}} primitive:
+\begin{center}\texttt{n := scantokens(}\textit{str}\texttt{);}\end{center}
+More generally, \texttt{scantokens} parses a string into a token
+sequence, as if MetaPost had read it as input.
+
+The boolean\index{boolean type} type has the constants {\tt
+true}\index{true?\texttt{true}}\label{Dtrue} and {\tt
+false}\index{false}\label{Dfalse} and the operators {\tt
+and}\index{and?\texttt{and}}\label{Dand}, {\tt
+or}\index{or?\texttt{or}}\label{Dor}, {\tt
+not}\index{not?\texttt{not}}\label{Dnot}. The relations \verb|=| and
+\verb|<>|\index{<>?\texttt{<>}}\label{Dcmpar} test objects of any type
+for equality and inequality\index{inequality}.
+Comparison\index{comparison} relations \verb|<|\index{<?\texttt{<}},
+\verb|<=|\index{<=?\texttt{<=}}, \verb|>|\index{>?\texttt{>}}, and
+\verb|>=|\index{>=?\texttt{>=}} are defined lexicographically for
+strings and in the obvious way for numerics. Ordering relations are
+also defined for booleans, pairs, colors, and transforms, but the
+comparison rules are not worth discussing here.
+
+The picture\index{picture type} data type is just what the name implies.
+Anything that can be drawn in MetaPost can be stored in a picture
+variable. In fact, the {\tt draw}\index{draw?\texttt{draw}} statement
+actually stores its results in a special picture variable called {\tt
+currentpicture}\index{currentpicture?\texttt{currentpicture}}. Pictures
+can be added to other pictures and operated on by transforms.
+
+Finally, there is a data type called a pen\index{pen type}. The main
+function of pens in MetaPost is to determine line thickness, but they
+can also be used to achieve calligraphic effects. The
+statement\index{pickup?\texttt{pickup}}\label{Dpickup}
+$$ {\tt pickup\ }\descr{pen expression} $$
+causes the given pen to be used in subsequent
+\verb|draw|\index{draw?\texttt{draw}} or
+\verb|drawdot|\index{drawdot?\texttt{drawdot}} statements. Normally,
+the pen expression is of the form
+$$ {\tt pencircle\ scaled\ }\descr{numeric primary}. $$
+This defines a circular pen that produces lines of constant thickness.
+If calligraphic effects are desired, the pen expression can be adjusted to give
+an elliptical pen or a polygonal pen.
+
+\subsection{Operators}
+
+There are many different ways to make expressions of the ten basic
+types, but most of the operations fit into a fairly simple syntax with
+four levels of precedence as shown in Figure~\ref{syexpr}. There are
+primaries\index{primary?\tdescr{primary}},
+secondaries\index{secondary?\tdescr{secondary}},
+tertiaries\index{tertiary?\tdescr{tertiary}}, and
+expressions\index{expression?\tdescr{expression}} of each of the basic
+types, so the syntax rules could be specialized to deal with items such
+as \tdescr{numeric primary}, \tdescr{boolean tertiary}, etc. This
+allows the result type for an operation to depend on the choice of
+operator and the types of its operands. For example, the {\tt <}
+relation is a \tdescr{tertiary binary} that can be applied to a
+\tdescr{numeric expression} and a \tdescr{numeric tertiary} to give a
+\tdescr{boolean expression}. The same operator can accept other operand
+types such as \tdescr{string expression} and \tdescr{string tertiary},
+but an error message results if the operand types do not match.
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{primary} \rightarrow \descr{variable}$\\
+$\tt \qquad \;|\; \hbox{\tt (}\descr{expression}\hbox{\tt )}$\\
+$\tt \qquad \;|\; \descr{nullary op}$\\
+$\tt \qquad \;|\; \descr{of operator} \descr{expression}
+ of \descr{primary}$\\
+$\tt \qquad \;|\; \descr{unary op} \descr{primary}$\\
+$\tt \descr{secondary} \rightarrow \descr{primary}$\\
+$\tt \qquad \;|\; \descr{secondary} \descr{primary binop} \descr{primary}$\\
+$\tt \descr{tertiary} \rightarrow \descr{secondary}$\\
+$\tt \qquad \;|\; \descr{tertiary} \descr{secondary binop}
+ \descr{secondary}$\\
+$\tt \descr{expression} \rightarrow \descr{tertiary}$\\
+$\tt \qquad \;|\; \descr{expression} \descr{tertiary binop}
+ \descr{tertiary}$
+\end{ctabbing}
+\caption{The overall syntax rules for expressions}
+\index{unary op?\tdescr{unary op}} \index{nullary op?\tdescr{nullary op}}
+\index{primary binop?\tdescr{primary binop}}
+\index{secondary binop?\tdescr{secondary binop}}
+\index{tertiary binop?\tdescr{tertiary binop}}
+\label{syexpr}
+\end{figure}
+
+The multiplication and division operators {\tt *}\label{Dmldiv} and~{\tt
+/} are examples of what Figure~\ref{syexpr} calls a \tdescr{primary
+binop}. Each can accept two numeric operands or one numeric operand and
+one operand of type pair or color. The exponentiation operator
+\verb|**|\index{**?\texttt{**}}\index{exponentiation}\label{Dpow} is a
+\tdescr{primary binop} that requires two numeric operands. Placing this
+at the same level of precedence as multiplication and division has the
+unfortunate consequence that \verb|3*a**2| means $(3a)^2$, not
+$3(a^2)$\index{parsing irregularities}. Since unary
+negation\label{Dneg} applies at the primary level, it also turns out
+that \verb|-a**2| means $(-a)^2$. Fortunately, subtraction has lower
+precedence so that \verb|a-b**2| does mean $a-(b^2)$ instead of
+$(a-b)^2$.
+
+Another \tdescr{primary binop} is the {\tt
+dotprod}\index{dotprod?\texttt{dotprod}}\label{Ddprod} operator that
+computes the vector dot product of two pairs. For example, {\tt z1
+dotprod z2} is equivalent to {\tt x1*x2 + y1*y2}.
+
+The additive operators {\tt +} and {\tt -}\label{Dadd} are
+\tdescr{secondary binops} that operate on numerics, pairs, or colors and
+produce results of the same type. Other operators that fall in this
+category are ``Pythagorean addition''
+\verb|++|\index{++?\texttt{++}}\label{Dpyadd} and ``Pythagorean
+subtraction'' \verb|+-+|\index{+-+?\texttt{+-+}}\label{Dpysub}:
+\verb|a++b| means $\sqrt{a^2+b^2}$ and \verb|a+-+b| means
+$\sqrt{a^2-b^2}$. There are too many other operators to list here, but
+some of the most important are the boolean operators {\tt
+and}\index{and?\texttt{and}} and {\tt or}\index{or?\texttt{or}}. The
+{\tt and} operator is a \tdescr{primary binop} and the {\tt or} operator
+is a \tdescr{secondary binop}.
+
+The basic operations on strings are concatenation\index{concatenation},
+substring construction and calculating the length of a string.
+The \tdescr{tertiary binop} \verb|&|\index{&?\texttt{\&}}\label{Damp}
+implements concatenation; e.g.,
+$$ \hbox{\verb|"abc" & "de"|} $$
+produces the string \verb|"abcde"|. The {\tt
+length}\index{length?\texttt{length}}\label{DlengthString} operator
+returns the number of characters in a string if the argument is a
+\tdescr{string primary}; e.g.,
+$$ \hbox{\verb|length "abcde"|} $$
+returns \verb|5|. Another application of the {\tt length} operator is
+discussed on p.\ \pageref{Dlength}. For substring construction, the
+\tdescr{of operator} {\tt substring}\index{substring
+of?\texttt{substring of}}\label{Dsubstr} is used like this:
+$$ {\tt substring}\, \descr{pair expression} \,{\tt of}\, \descr{string primary} $$
+The \tdescr{pair expression} determines what part of the string to
+select. For this purpose, the string is indexed\index{indexing} so that
+integer positions fall {\em between\/} characters. Pretend the string
+is written on a piece of graph paper so that the first character
+occupies $x$~coordinates between zero and one and the next character
+covers the range $1\le x\le2$, etc. Thus the string \verb|"abcde"|
+should be thought of like this
+$$ \includegraphics{mpman-14.mps} $$
+and {\tt substring (2,4) of "abcde"} is {\tt "cd"}. This takes a little
+getting used to but it tends to avoid annoying ``off by one'' errors.
+
+Some operators take no arguments at all. An example of what
+Figure~\ref{syexpr} calls a \tdescr{nullary op} is {\tt
+nullpicture}\index{nullpicture?\texttt{nullpicture}}\label{Dnlpic} which
+returns a completely blank picture.
+
+The basic syntax in Figure~\ref{syexpr} only covers aspects of the
+expression syntax that are relatively type-independent. For instance,
+the complicated path syntax given in Figure~\ref{sypath} gives
+alternative rules for constructing a \tdescr{path expression}. An
+additional rule\index{path knot?\tdescr{path knot}}
+$$ \descr{path knot} \rightarrow \descr{pair tertiary} \;|\; \descr{path tertiary}
+$$
+explains the meaning of \tdescr{path knot} in Figure~\ref{sypath}. This means
+that the path expression
+$$ \hbox{\verb|z1+(1,1){right}..z2|} $$
+does not need parentheses around {\tt z1+(1,1)}.
+
+\subsection{Fractions, Mediation, and Unary Operators}
+
+Mediation\index{mediation} expressions do not appear in the basic expression
+syntax of Figure~\ref{syexpr}. Mediation expressions are parsed at the
+\tdescr{primary} level, so the general rule for constructing them is
+$$ \descr{primary} \rightarrow
+ \descr{numeric atom} \hbox{\tt [} \descr{expression}
+ \hbox{\tt ,} \descr{expression} \hbox{\tt ]}
+$$
+where each \tdescr{expression} can be of type numeric, pair, or color.
+The \tdescr{numeric atom}\index{numeric atom?\tdescr{numeric atom}} in a
+mediation expression is an extra simple type of \tdescr{numeric primary}
+as shown in Figure~\ref{synprim}. The meaning of all this is that the
+initial parameter in a mediation expression needs to be parenthesized
+when it is not just a variable, a positive number, or a positive
+fraction. For example,\index{parsing irregularities}
+$$ \hbox{\tt -1[a,b]} \quad {\rm and}\quad \hbox{\tt (-1)[a,b]} $$
+are very different: the former is $-b$ since it is equivalent to
+{\tt -(1[a,b])}; the latter is $a-(b-a)$ or $2a-b$.
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{numeric primary} \rightarrow \descr{numeric atom}$\\
+$\tt \qquad \;|\; \descr{numeric atom}\hbox{\tt [}
+ \descr{numeric expression}\hbox{\tt ,}\descr{numeric expression}\hbox{\tt ]}$\\
+$\tt \qquad \;|\; \descr{of operator} \descr{expression} of \descr{primary}$\\
+$\tt \qquad \;|\; \descr{unary op} \descr{primary}$\\
+$\tt \descr{numeric atom} \rightarrow \descr{numeric variable}$\\
+$\tt \qquad \;|\; \descr{number or fraction}$\\
+$\tt \qquad \;|\; \hbox{\tt (}\descr{numeric expression}\hbox{\tt )}$\\
+$\tt \qquad \;|\; \descr{numeric nullary op}$\\
+$\tt \descr{number or fraction} \rightarrow \descr{number}
+ \hbox{\tt /}\descr{number}$\\
+$\tt \qquad \;|\; \descr{number not followed by
+ `$\hbox{\tt /}\descr{number}$'}$
+\end{ctabbing}
+\caption{Syntax rules for numeric primaries}
+\label{synprim}
+\end{figure}
+
+A noteworthy feature of the syntax rules in Figure~\ref{synprim} is that
+the {\tt /}\index{fractions} operator binds most tightly when its
+operands are numbers. Thus {\tt 2/3} is a \tdescr{numeric
+atom}\index{numeric atom?\tdescr{numeric atom}}\index{parsing
+irregularities} while {\tt (1+1)/3} is only a \tdescr{numeric
+secondary}. Applying a \tdescr{unary op} such as {\tt
+sqrt}\index{sqrt?\texttt{sqrt}}\label{Dsqrt} makes the difference clear:
+$$ \hbox{\tt sqrt 2/3} $$
+means $\sqrt{2\over3}$ while
+$$ \hbox{\tt sqrt(1+1)/3} $$
+means $\sqrt 2/3$. Operators such as {\tt sqrt} can be written in
+standard functional notation, but it is often unnecessary to
+parenthesize the argument. This applies to any function that is parsed
+as a \tdescr{unary op}. For instance {\tt
+abs(x)}\index{abs?\texttt{abs}}\label{Dabs} and {\tt abs x} both compute
+the absolute value of {\tt x}. The same holds for the {\tt
+round}\index{round?\texttt{round}}\label{Dround}, {\tt
+floor}\index{floor?\texttt{floor}}\label{Dfloor}, {\tt
+ceiling}\index{ceiling?\texttt{ceiling}}\label{Dceil}, {\tt
+sind}\index{sind?\texttt{sind}}\label{Dsind}, and {\tt
+cosd}\index{cosd?\texttt{cosd}}\label{Dcosd} functions. The last two of
+these compute trigonometric functions of angles in degrees.
+
+Not all unary operators take numeric arguments and return numeric
+results. For instance, the {\tt abs}\index{abs?\texttt{abs}} operator
+can be applied to a pair to compute the Euclidean length of a vector.
+Applying the {\tt
+unitvector}\index{unitvector?\texttt{unitvector}}\label{Duvec} operator
+to a pair produces the same pair rescaled so that its Euclidean length
+is~1. The {\tt decimal}\index{decimal?\texttt{decimal}}\label{Ddecop}
+operator takes a number and returns the string representation. The {\tt
+angle}\index{angle?\texttt{angle}}\label{Dangle} operator takes a pair
+and computes the two-argument arctangent; i.e., {\tt angle} is the
+inverse of the {\tt dir} operator that was discussed in
+Section~\ref{tenscurl}. There is also an operator {\tt
+cycle}\index{cycle?\texttt{cycle}}\label{Dcycop} that takes a
+\tdescr{path primary} and returns a boolean result indicating whether
+the path is a closed curve.
+
+There is a whole class of other operators that classify expressions and
+return boolean results. A type name such as {\tt
+pair}\index{pair?\texttt{pair}} can operate on any type of
+\tdescr{primary} and return a boolean result indicating whether the
+argument is a {\tt pair}\label{Dpairop}. Similarly, each of the
+following can be used as a unary operator:
+{\tt numeric}\index{numeric?\texttt{numeric}}\label{Dnumop},
+{\tt boolean}\index{boolean?\texttt{boolean}}\label{Dboolop},
+{\tt cmykcolor}\index{cmykcolor?\texttt{cmykcolor}}\label{Dccolrop},
+{\tt color}\index{color?\texttt{color}}\label{Dcolrop},
+{\tt string}\index{string?\texttt{string}}\label{Dstrgop},
+{\tt transform}\index{transform?\texttt{transform}}\label{Dtrnfop},
+{\tt path}\index{path?\texttt{path}}\label{Dpathop},
+{\tt pen}\index{pen?\texttt{pen}}\label{Dpenop},
+{\tt picture}\index{picture?\texttt{picture}}\label{Dpictop}, and
+{\tt rgbcolor}\index{rgbcolor?\texttt{rgbcolor}}\label{Drcolrop}.
+Besides just
+testing the type of a \tdescr{primary}, you can use the {\tt
+known}\index{known?\texttt{known}}\label{Dknown} and {\tt
+unknown}\index{unknown?\texttt{unknown}}\label{Dunknwn} operators to
+test if it has a completely known value.
+
+Even a number can behave like an operator in some contexts. This refers
+to the trick that allows {\tt 3x}\index{multiplication, implicit} and
+{\tt 3cm} as alternatives to {\tt 3*x} and {\tt 3*cm}. The rule is that
+a \tdescr{number or fraction} that is not followed by {\tt +}, {\tt -},
+or another \tdescr{number or fraction} can serve as a \tdescr{primary
+binop}. Thus {\tt 2/3x}\index{parsing irregularities} is two thirds of
+{\tt x} but {\tt (2)/3x} is $2\over3x$ and {\tt 3 3} is illegal.
+
+There are also operators for extracting numeric subfields from pairs,
+colors, cmykcolors, and even transforms. If {\tt p} is a \tdescr{pair
+primary}, {\tt xpart p}\index{xpart?\texttt{xpart}}\label{Dxprt} and
+{\tt ypart p}\index{ypart?\texttt{ypart}}\label{Dyprt} extract its components so that
+$$ \hbox{\tt (xpart p, ypart p)} $$ is equivalent to~{\tt p} even if
+{\tt p} is an unknown pair that is being used in a linear equation.
+Similarly, a color {\tt c} is equivalent
+to\index{redpart?\texttt{redpart}}%
+\index{greenpart?\texttt{greenpart}}%
+\index{bluepart?\texttt{bluepart}}\label{Drgbprt}
+$$ \hbox{\tt (redpart c, greenpart c, bluepart c)}. $$
+For a cmykcolor {\tt c}, the components are%
+\index{cyanpart?\texttt{cyanpart}}%
+\index{magentapart?\texttt{magentapart}}%
+\index{yellowpart?\texttt{yellowpart}}%
+\index{blackpart?\texttt{blackpart}}\label{Dcmykprt}
+$$ \hbox{\tt (cyanpart c, magentapart c, yellowpart c, blackpart c)} $$
+and for a greyscale color {\tt c}, there is only one component%
+\index{greypart?\texttt{greypart}}\label{Dgreyprt}%
+$$ \hbox{\tt greypart c}. $$
+All color component operators are discussed in more detail in
+section~\ref{piccomp}. Part specifiers for transforms are discussed
+in section~\ref{transsec}.
+
+
+\section{Variables}
+\label{vars}
+
+MetaPost allows compound variable names such as {z.a}, {\tt x2r}, {\tt y2r},
+and {\tt z2r}, where {\tt z2r} means {\tt (x2r,y2r)} and {\tt z.a} means
+{\tt (x.a,y.a)}. In fact there is a broad class of suffixes such that
+{\tt z}\tdescr{suffix}\index{suffix?\tdescr{suffix}} means
+$$ (x\descr{suffix},\, y\descr{suffix}). $$
+Since a \tdescr{suffix} is composed of tokens, it is best to begin with a few
+comments about tokens.
+
+\subsection{Tokens}
+
+A MetaPost input file is treated as a sequence of numbers, string
+constants, and symbolic tokens\index{tokens}\index{tokens!symbolic}. A
+number consists of a sequence of digits possibly containing a decimal
+point. Technically, the minus sign in front of a negative number is a
+separate token. Since MetaPost uses fixed point
+arithmetic\index{arithmetic}, it does not understand exponential
+notation such as {\tt 6.02E23}. MetaPost would interpret this as the
+number 6.02, followed by the symbolic token {\tt E}, followed by the
+number~23.
+
+Anything between a pair of double quotes {\tt "} is a
+string constant\index{string constants}. It is
+illegal for a string constant to start on one line and end on a later line.
+Nor can a string constant contain double quotes {\tt "} or anything other than
+printable ASCII characters.
+
+Everything in a line of input other than numbers and string constants is broken
+into symbolic tokens\index{tokens!symbolic}. A symbolic token is a sequence of
+one or more similar characters, where characters are ``similar'' if they occur
+on the same row of Table~\ref{classes}.
+
+\begin{table}
+$$\begin{tabular}{c}
+\verb|ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz|\\
+{\tt :<=>|}\\
+\verb|#&@$|\\
+\verb|/*\|\\
+{\tt +-}\\
+{\tt !?}\\
+{\tt '`}\\
+\verb|^~|\\
+\verb|{}|\\
+{\tt [}\\
+{\tt ]}\\
+\end{tabular}
+$$
+\caption{Character classes for tokenization}
+\label{classes}
+\end{table}
+
+Thus \verb|A_alpha| and {\tt +-+} are symbolic tokens but {\tt !=} is
+interpreted as two tokens and {\tt x34} is a symbolic token followed by
+a number. Since the brackets {\tt [} and {\tt ]} are listed on lines by
+themselves, the only symbolic tokens involving them are {\tt [}, {\tt
+[[}, {\tt [[[}, etc.\ and {\tt ]}, {\tt ]]}, etc.
+
+Some characters are not listed in Table~\ref{classes} because they need
+special treatment. The four characters {\tt ,;()} are ``loners'': each
+comma, semicolon, or parenthesis is a separate token even when they
+occur consecutively. Thus {\tt (())} is four tokens, not one or two.
+The percent sign is very special because it introduces
+comments\index{\%?\texttt{\%}!comment}\index{comments}. The percent
+sign and everything after it up to the end of the line are ignored.
+
+Another special character is the period. Two or more periods
+together form a symbolic token, but a single period is ignored, and a period
+preceded or followed by digits is part of a number Thus {\tt ..}
+and {\tt ...} are symbolic tokens while {\tt a.b} is just two tokens {\tt a}
+and {\tt b}. It conventional to use periods to separate tokens in this fashion
+when naming a variable that is more than one token long.
+
+\subsection{Variable Declarations}
+\label{vardecl}
+
+A variable name is a symbolic token or a sequence of symbolic tokens.
+Most symbolic tokens are legitimate variable names, but anything with a
+predefined meaning like {\tt draw}, {\tt +}, or {\tt ..} is disallowed;
+i.e., variable names cannot be macros or MetaPost primitives. This
+minor restriction allows an amazingly broad class of variable names:
+{\tt alpha}, \verb|==>|, \verb|@&#$&|, and \verb|~~| are all legitimate
+variable names. Such symbolic tokens without special meanings are
+called {\em tags}\index{tags}.
+
+A variable name can be a sequence of tags like {\tt f.bot} or {\tt
+f.top}. The idea is to provide some of the functionality of Pascal
+records or C structures. It is also possible to simulate arrays by
+using variable names that contain numbers as well as symbolic tokens.
+For example, the variable name {\tt x2r} consists of the tag {\tt x},
+the number 2, and the tag~{\tt r}. There can also be variables named
+{\tt x3r} and even {\tt x3.14r}. These variables can be treated as an
+array\index{arrays} via constructions like {\tt x[i]r}, where {\tt i}
+has an appropriate numeric value. The overall syntax for variable names
+is shown in Figure~\ref{syvar}.
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{variable} \rightarrow \descr{tag}\descr{suffix}$\\
+$\tt \descr{suffix} \rightarrow \descr{empty} \;|\;
+ \descr{suffix}\descr{subscript} \;|\; \descr{suffix}\descr{tag}$\\
+$\tt \descr{subscript} \rightarrow \descr{number} \;|\;
+ \hbox{\tt [}\descr{numeric expression}\hbox{\tt ]}$
+\end{ctabbing}
+\caption{The syntax for variable names.}
+\index{suffix?\tdescr{suffix}}\index{subscript?\tdescr{subscript}}
+\label{syvar}
+\end{figure}
+
+Variables like {\tt x2} and {\tt y2} take on numeric values by default, so we
+can use the fact that {\tt z}\tdescr{suffix} is an abbreviation for\index{z convention?{\tt z} convention}\label{Dzconv}
+$$ (x\descr{suffix},\, y\descr{suffix}) $$
+to generate pair-valued variables when needed. It turns out that the
+{\tt beginfig}\index{beginfig?\texttt{beginfig}} macro wipes out
+pre-existing values variables that begin with the tags {\tt x} or {\tt
+y} so that {\tt beginfig} \ldots\ {\tt endfig} blocks do not interfere
+with each other when this naming scheme is used. In other words,
+variables that start with {\tt x}, {\tt y}, {\tt z} are
+local\index{variables!local}\index{locality} to the figure they are used
+in. General mechanisms for making variables local will be discussed in
+Section~\ref{grsec}.
+
+Type declarations\index{declarations}\index{type declarations}
+make it possible to use almost any naming scheme while still
+wiping out any previous value that might cause interference. For example, the
+declaration
+$$ \hbox{\tt pair pp, a.b;} $$
+makes {\tt pp} and {\tt a.b} unknown pairs. Such a declaration is not
+strictly local since {\tt pp} and {\tt a.b} are not automatically
+restored to their previous values at the end of the current figure. Of
+course, they are restored to unknown pairs if the declaration is
+repeated.
+
+Declarations work the same way for any of the other nine types: numeric,
+path, transform, color, cmykcolor, string, boolean, picture, and pen. The
+only restriction is that you cannot give explicit numeric subscripts in
+a variable declaration. Do not give the illegal declaration
+$$ \hbox{\tt numeric q1, q2, q3;} $$
+use the generic subscript\index{subscript!generic} symbol
+{\tt []}\index{arrays}\index{[]?\texttt{[]}!array}
+instead, to declare the whole array:
+$$ \hbox{\tt numeric q[];} $$
+You can also declare ``multidimensional'' arrays\index{arrays!multidimensional}.
+After the declaration
+$$ \hbox{\tt path p[]q[], pq[][];} $$
+{\tt p2q3} and {\tt pq1.4 5} are both paths.
+
+Internal\index{internal variables}\index{variables!internal} variables
+like {\tt tracingonline} cannot be declared in the normal fashion. All
+the internal variables discussed in this manual are predefined and do
+not have to be declared at all, but there is a way to declare that a
+variable should behave like a newly-created internal variable. The
+declaration is {\tt
+ newinternal}\index{newinternal?\texttt{newinternal}}\label{Dnewint}
+followed by an optional type specifier \texttt{numeric}\index{internal
+ variables!\texttt{numeric}}\index{variables!internal!\texttt{numeric}}
+or \texttt{string}\index{internal
+ variables!\texttt{string}}\index{variables!internal!\texttt{string}}
+and a list of symbolic tokens. For example,
+$$\begin{verbatim}
+newinternal numeric n, m;
+newinternal string s, t;
+newinternal num;
+\end{verbatim}
+$$
+are valid declarations that declare three internal numeric variables
+\texttt{n}, \texttt{m}, and~\texttt{num} and two internal string
+variables \texttt{s} and~\texttt{t}.
+
+Internal variables always have known values, and these values can only
+be changed by using the assignment\index{assignment} operator
+{\tt:=}\index{:=?\texttt{:=}}. Internal numeric variables are initially
+zero and internal string variables are initially the empty
+string~\verb|""|, except that the Plain\index{Plain macros} macro
+package gives some of the variables different initial values. (The
+Plain macros are normally preloaded automatically as explained in
+Section~\ref{intro}.)
+
+Internal string variables have been introduced in MetaPost
+version~1.200. For backwards compatibility, if the type specifier is
+missing, internal variables default to a \texttt{numeric}\index{internal
+ variables!\texttt{numeric}}\index{variables!internal!\texttt{numeric}}
+type, as in the last example. The declarations \texttt{newinternal
+ numeric;} and \texttt{newinternal string;} are invalid and throw an
+error.
+
+
+\section{Integrating Text and Graphics}
+\label{text}
+
+MetaPost has a number of features for including labels and other
+text\index{text and graphics} in the figures it generates. The simplest
+way to do this is to use the {\tt
+label}\index{label?\texttt{label}}\label{Dlabel} statement\index{label
+suffix?\tdescr{label suffix}}
+$$ {\tt label}\descr{label suffix} \hbox{\tt (}
+ \descr{string or picture expression} \hbox{\tt,}\, \descr{pair expression}
+ \hbox{\tt );}
+$$
+The \tdescr{string or picture expression} gives the label and the
+\tdescr{pair expression} says where to put it. The \tdescr{label
+suffix} can be \tdescr{empty} in which case the label is just centered
+on the given coordinates. If you are labeling some feature of a diagram
+you probably want to offset the label slightly to avoid overlapping.
+This is illustrated in Figure~\ref{fig16} where the {\tt "a"} label is
+placed above the midpoint of the line it refers to and the {\tt "b"}
+label is to the left of the midpoint of its line. This is achieved by
+using {\tt label.top}\index{top?\texttt{top}} for the {\tt "a"} label
+and {\tt label.lft}\index{lft?\texttt{lft}} for the {\tt "b"} label as
+shown in the figure. The \tdescr{label suffix} specifies the position
+of the label relative to the specified coordinates. The complete set of
+possibilities is\index{rt?\texttt{rt}}\index{bot?\texttt{bot}}%
+\index{ulft?\texttt{ulft}}\index{urt?\texttt{urt}}\index{llft?\texttt{llft}}\index{lrt?\texttt{lrt}}
+$$ \tt \descr{label suffix} \rightarrow
+ \descr{empty} \;|\; lft \;|\; rt \;|\; top \;|\; bot \;|\;
+ ulft \;|\;urt \;|\; llft \;|\; lrt
+$$
+where {\tt lft} and {\tt rt} mean left and right and {\tt llft}, {\tt
+ulft}, etc.\ mean lower left, upper left, etc. The actual amount by
+which the label is offset in whatever direction is determined by the
+internal variable\index{internal variables}\index{variables!internal}
+{\tt
+labeloffset}\index{labeloffset?\texttt{labeloffset}}\label{Dlaboff}.
+
+\begin{figure}[htp]
+$$
+\begin{verbatim}
+beginfig(17);
+a=.7in; b=.5in;
+z0=(0,0);
+z1=-z3=(a,0);
+z2=-z4=(0,b);
+draw z1..z2..z3..z4..cycle;
+draw z1--z0--z2;
+label.top("a", .5[z0,z1]);
+label.lft("b", .5[z0,z2]);
+dotlabel.bot("(0,0)", z0);
+endfig;
+\end{verbatim}
+\qquad \mathcenter{\includegraphics{mpman-17.mps}}
+$$
+\caption{MetaPost code and the resulting output}
+\label{fig16}
+\end{figure}
+
+Figure~\ref{fig16} also illustrates the
+{\tt dotlabel}\index{dotlabel?\texttt{dotlabel}}\label{Ddotlab}
+statement. This is effectively
+like a {\tt label} statement followed by a statement drawing a dot at
+the indicated coordinates. For example
+$$ \hbox{\tt dotlabel.bot("(0,0)", z0)} $$
+places a dot at {\tt z0} and then puts the label ``(0,0)'' just below
+the dot. The diameter of the dot drawn by the {\tt dotlabel} statement
+is determined by the value of the internal variable {\tt
+ dotlabeldiam}\index{dotlabeldiam?\texttt{dotlabeldiam}}\label{Ddotlabdiam}.
+Default value is 3bp.
+
+Another alternative is the macro
+{\tt thelabel}\index{thelabel?\texttt{thelabel}}\label{Dthelab}. This has
+the same syntax as the {\tt label} and {\tt dotlabel} statements except that it
+returns the label as a \tdescr{picture primary} instead of actually drawing it.
+Thus
+$$ \hbox{\tt label.bot("(0,0)", z0)} $$
+is equivalent to
+$$ \hbox{\tt draw thelabel.bot("(0,0)", z0)} $$
+
+For simple applications of labeled figures, you can normally get by with
+just {\tt label} and {\tt dotlabel}. In fact, you may be able to use a
+short form of the {\tt dotlabel} statement that saves a lot of typing
+when you have many points {\tt z0}, {\tt z1}, {\tt z.a}, {\tt z.b},
+etc.\ and you want to use the {\tt z} suffixes as labels. The
+statement\index{dotlabels?\texttt{dotlabels}}\label{Ddotlbs}
+$$ \hbox{\tt dotlabels.rt(0, 1, a);} $$
+is equivalent to
+$$ \hbox{\tt dotlabel.rt("0",z0); dotlabel.rt("1",z1); dotlabel.rt("a",z.a);} $$
+Thus the argument to {\tt dotlabels} is a list of suffixes for which {\tt z}
+variables are known, and the \tdescr{label suffix} given with {\tt dotlabels}
+is used to position all the labels.
+
+There is also a {\tt
+labels}\index{labels?\texttt{labels}}\label{Dlabels} statement that is
+analogous to {\tt dotlabels} but its use is discouraged because it
+presents compatibility problems with \MF\index{metafont?\MF}. Some
+versions of the preloaded Plain\index{Plain macros} macro package define
+{\tt labels} to be synonymous with {\tt dotlabels}.
+
+For labeling statements such as {\tt label} and {\tt dotlabel} that use
+a string expression for the label text, the string gets typeset in a
+default font as determined by the string variable {\tt
+defaultfont}\index{defaultfont?\texttt{defaultfont}}\label{Ddffont}.
+The initial value of {\tt defaultfont} is likely to be {\tt "cmr10"},
+but it can be changed to a different font name by giving an assignment
+such as
+$$ \hbox{\tt defaultfont:="ptmr8r"} $$
+\ttt{ptmr8r} is a typical way to refer to the Times-Roman font in \TeX.
+The discussion of font names on p.\ \pageref{fontname} explains further.
+
+There is also a numeric quantity called
+{\tt defaultscale}\index{defaultscale?\texttt{defaultscale}}\label{Ddfscale}
+that determines the type size.
+When {\tt default\-scale} is 1, you get the ``normal size'' which is
+usually 10 point, but this can also be changed. For instance
+$$ \hbox{\tt defaultscale := 1.2} $$
+makes labels come out twenty percent larger. If you do not know the
+normal size and you want to be sure the text comes out at some specific
+size, say 12 points, you can use the {\tt
+fontsize}\index{fontsize?\texttt{fontsize}}\label{Dfntsiz} operator to
+determine the normal size: e.g.,
+$$ \hbox{\tt defaultscale := 12pt/fontsize defaultfont;} $$
+
+\label{fontname}
+When you change {\tt defaultfont}, the new font name should be something
+that \TeX\ would understand since MetaPost gets height and width
+information by reading a {\tt tfm}\index{tfm file?{\tt tfm}
+file}\index{files!tfm?{\tt tfm}} file. (This is explained in {\sl The
+\TeX book\/} \cite{kn:a}.) It should be possible to use built-in
+PostScript\index{PostScript!fonts} fonts, but the names for
+them are system-dependent. Some typical ones are {\tt ptmr8r} for
+Times-Roman\index{Times-Roman}, \ttt{pplr8r} for Palatino\index{Palatino},
+and \ttt{phvr} for Helvetica\index{Helvetica}. The Fontname document,
+available at \url{http://tug.org/fontname}, has much more information
+about font names and \TeX. A \TeX\index{TeX?\TeX!fonts} font such
+as {\tt cmr10} is a little dangerous because it does not have a space
+character or certain ASCII symbols.
+
+MetaPost does not use the ligatures\index{ligatures} and
+kerning\index{kerning} information that comes with a \TeX\ font.
+Further, MetaPost itself does not interpret virtual fonts.
+
+
+\subsection{Typesetting Your Labels}
+
+\label{Dbtex}
+\index{labels, typesetting}
+
+\TeX\index{TeX?\TeX} may be used to format complex labels.
+If you say\index{btex?\texttt{btex}}\index{etex?\texttt{etex}}
+$$ {\tt btex}\, \descr{typesetting commands}\, {\tt etex} $$
+in a MetaPost input file, the \tdescr{typesetting commands} get processed by
+\TeX\ and translated into a picture expression
+(actually a \tdescr{picture primary}) that can be used in a {\tt label}
+or {\tt dotlabel} statement. Any spaces after {\tt btex} or before {\tt etex}
+are ignored. For instance, the statement
+$$ \hbox{\verb|label.lrt(btex $\sqrt x$ etex, (3,sqrt 3)*u)|} $$
+in Figure~\ref{fig17} places the label $\sqrt x$ at the lower right of the
+point {\tt (3,sqrt 3)*u}.
+
+\begin{figure}[htp]
+$$
+\begin{verbatim}
+beginfig(18);
+numeric u;
+u = 1cm;
+draw (0,2u)--(0,0)--(4u,0);
+pickup pencircle scaled 1pt;
+draw (0,0){up}
+ for i=1 upto 8: ..(i/2,sqrt(i/2))*u endfor;
+label.lrt(btex $\sqrt x$ etex, (3,sqrt 3)*u);
+label.bot(btex $x$ etex, (2u,0));
+label.lft(btex $y$ etex, (0,u));
+endfig;
+\end{verbatim}
+\qquad \mathcenter{\includegraphics{mpman-18.mps}}
+$$
+\caption{Arbitrary \TeX\ as labels}
+\label{fig17}
+\end{figure}
+
+Figure~\ref{fig18} illustrates some of the more complicated things that can
+be done with labels. Since the result of {\tt btex} \ldots {\tt etex} is
+a picture, it can be operated on like a picture. In particular, it is possible
+to apply transformations to pictures. We have not discussed the syntax for
+this yet, but a \tdescr{picture secondary}
+can be\index{rotated text}\index{rotated?\texttt{rotated}}
+$$ \descr{picture secondary}\, {\tt rotated}\, \descr{numeric primary} $$
+This is used in Figure~\ref{fig18} to rotate the label ``$y$ axis'' so that
+it runs vertically.
+
+\begin{figure}[htp]
+$$
+\begin{verbatim}
+beginfig(19);
+numeric ux, uy;
+120ux=1.2in; 4uy=2.4in;
+draw (0,4uy)--(0,0)--(120ux,0);
+pickup pencircle scaled 1pt;
+draw (0,uy){right}
+ for ix=1 upto 8:
+ ..(15ix*ux, uy*2/(1+cosd 15ix))
+ endfor;
+label.bot(btex $x$ axis etex, (60ux,0));
+label.lft(btex $y$ axis etex rotated 90,
+ (0,2uy));
+label.lft(
+ btex $\displaystyle y={2\over1+\cos x}$ etex,
+ (120ux, 4uy));
+endfig;
+\end{verbatim}
+\qquad \mathcenter{\includegraphics{mpman-19.mps}}
+$$
+\caption{\TeX\ labels with display math, and rotated by MetaPost}
+\label{fig18}
+\end{figure}
+
+Another complication in Figure~\ref{fig18} is the use of the displayed equation
+$$y={2\over 1+\cos x}$$
+as a label. It would be more natural to code this as
+$$ \hbox{\verb|$$y={2\over 1+\cos x}$$|} $$
+but this would not work because
+\TeX\ typesets the labels in ``horizontal mode.''
+
+For a way to typeset \emph{variable} text as labels, see the
+\texttt{TEX} utility routine described on p.\ \pageref{dTEX}.
+
+Here is how \TeX\ material gets translated into a form MetaPost
+understands: MetaPost stores all {\tt btex}\index{btex?\texttt{btex}}
+\ldots\ {\tt etex}\index{etex?\texttt{etex}} blocks in a temporary
+file and then runs \TeX\ on that file. If the environment variable
+\ttindex{MPTEXPRE} is set to the name of an existing file, its content
+will be prepended to the output file for processing by \TeX. You can
+use this to include \LaTeX\ preambles, for instance. The \ttt{TEX}
+macro described on p.\ \pageref{dTEX} provides another way to handle
+this.
+
+Once the \TeX\ run is finished, MetaPost translates the resulting
+DVI\index{dvi file?{\tt dvi} file}\index{files!dvi?{\tt dvi}} file into
+low level MetaPost commands that are then read instead of the {\tt btex}
+\ldots\ {\tt etex} blocks. If the main file is {\tt fig.mp}, the
+translated \TeX\ material is placed in a file named {\tt
+ fig.mpx}\index{mpx file?{\tt mpx} file}\index{files!mpx?{\tt mpx}}.
+
+The conversion normally runs silently without any user intervention but
+it could fail, for instance if one of the {\tt btex} \ldots {\tt etex}
+blocks contains an erroneous \TeX\index{TeX?\TeX!errors} command. In
+that case, the \TeX\ input is saved in the file {\tt
+ mpxerr.tex}\index{mpxerr.tex?\texttt{mpxerr.tex}} and the \TeX\ error
+messages appear in {\tt
+ mpxerr.log}\index{mpxerr.log?\texttt{mpxerr.log}}\index{log file?{\tt
+ log} file}\index{files!log?{\tt log}}.
+
+The DVI to MetaPost conversion route {\it does\/} understand virtual
+fonts, so you can use your normal \TeX\ font switching commands inside
+the label.
+
+
+\label{Dmakempx}
+In MetaPost versions before 1.100, the \TeX\ label preprocessing was
+handled by an external program that was called upon automatically by
+MetaPost. On Web2C-based systems, the preprocessor was normally named
+\ttindex{makempx}, which called the utility \ttindex{mpto} for the
+creation of the \TeX\ input file and the utility \texttt{dvitomp}\index{dvitomp?\texttt{dvitomp}} for
+the conversion to low level MetaPost. In the current MetaPost version,
+the work of this program is now done internally. However, if the
+environment variable \ttindex{MPXCOMMAND} is set, the whole label
+conversion mechanism will be delegated to the command given in that
+variable.
+
+
+\label{Dverbatimtex}
+\TeX\ macro definitions or any other auxiliary \TeX\ commands can be
+enclosed in a {\tt verbatimtex}\index{verbatimtex?\texttt{verbatimtex}}
+\ldots\ {\tt etex}\index{etex?\texttt{etex}} block. The difference
+between {\tt btex} and {\tt verbatimtex} is that the former generates a
+picture expression while the latter only adds material for \TeX\ to
+process. For instance, if you want \TeX\ to typeset labels using macros
+defined in {\tt mymac.tex}, your MetaPost input file would look
+something like this:
+\begin{eqnarray*}
+&& \verb|verbatimtex \input mymac etex|\\
+&& \verb|beginfig(1);|\\
+&& \qquad \dots\\
+&& \verb|label(btex|\, \descr{\TeX\ material using \hbox{\tt mymac.tex}}\,
+ \verb|etex, | \descr{some coordinates} \hbox{\tt );}\\
+&& \qquad \dots
+\end{eqnarray*}
+
+\label{Dtroffmode}
+On Unix\footnote{Unix is a registered trademark of Unix Systems
+Laboratories.}\index{Unix} and other Web2C-based systems, the
+option {\tt -troff} to MetaPost tells the preprocessor that {\tt btex}
+$\ldots$ {\tt etex} and {\tt verbatimtex} $\ldots$ {\tt etex} blocks
+are in troff\index{troff} instead of \TeX. When using this option,
+MetaPost sets the internal variable
+\ttindex{troffmode} to~1\index{prologues?\texttt{prologues}}.
+
+\label{Dprologues}
+Setting \ttt{prologues} can be useful with \TeX, too, not just troff.
+Here is some explanation:
+
+\begin{itemize}
+\item In PostScript output mode, when \ttt{prologues} is 0, which is the default, the MetaPost
+output files do not have embedded fonts. Fonts in the resulting
+output will probably render as Courier\index{Courier} or
+Times-Roman\index{Times-Roman}.
+
+In SVG mode, the text will probably render in a generic sans serif font.
+There may very well be problems with the encoding of non-ASCII characters:
+the font model of SVG is totally different from the model used by MetaPost.
+
+\item In PostScript output mode, when \ttt{prologues} is 1, the MetaPost output claims to be
+``structured PostScript''\index{PostScript!structured} (EPSF\index{EPSF}),
+but it is not completely conformant. This variant is kept for backward
+compatibility with old (troff) documents, but its use is deprecated.
+MetaPost sets \ttt{prologues} to~1 when the {\tt -troff} option is given
+on the command line.
+
+A \ttt{prologues:=1} setting is currently ignored in SVG output
+mode. The value is reserved for future use (possibly for mapping to
+\ttt{font-family}, \ttt{font-weight}, etc. properties).
+
+\item In PostScript output mode, when \ttt{prologues} is 2, the
+MetaPost output is EPSF and assumes
+that the text comes from PostScript\index{PostScript!fonts} fonts
+provided by the ``environment'', such as the document viewer or
+embedded application using the output. MetaPost will attempt to
+set up the font encodings correctly, based on \ttt{fontmapfile} and
+\ttt{fontmapline} commands.
+
+A \ttt{prologues:=2} setting is currently ignored in SVG output mode.
+The value is reserved for future use (possibly for external
+\ttt{font-face} definitions).
+
+\item In PostScript output mode, when \ttt{prologues} is 3, the MetaPost output will be EPSF but
+will contain the PostScript font(s) (or a subset) used based on the
+\ttt{fontmapfile} and \ttt{fontmapline} commands. This value is useful
+for generating stand-alone PostScript graphics.
+
+In SVG mode, the font glyphs are converted to path definitions that
+are included at the top of the output file.
+
+\end{itemize}
+
+The correct setting for variable \texttt{prologues} depends on how
+MetaPost graphics are post-processed. Here are recommendations for some
+popular use-cases:
+
+\begin{description}
+
+\item[\normalfont\itshape Previewing:] Section~\ref{preview} discusses
+ previewing PostScript output.
+
+\item[\normalfont\itshape \TeX\ and dvips:] When including PostScript
+ figures into a \TeX\ document that is processed by \TeX\ and a DVI
+ output processer, e.g., dvips\index{dvips}, variable
+ \texttt{prologues} should \emph{not} be set to the value~1, unless the
+ used fonts are known to be resident in the PostScript interpreter.
+ Make sure that variable \texttt{prologues} is set to either~0 (font
+ inclusion handled by dvips, but without re-encoding support), 2 (font
+ inclusion by dvips, with font re-encoding if necessary), or~3 (font
+ inclusion and re-encoding by MetaPost). Value~3 is safest, but may
+ result in slightly larger output.
+
+\item[\normalfont\itshape pdf\TeX:] When generating PDF files with
+ pdf\TeX\ (and the mptopdf\index{mptopdf} bundle), variable
+ \texttt{prologues} is not relevant.
+
+\item[\normalfont\itshape PostScript in external applications:] Some
+ text\index{text processor} processors or graphics applications can
+ directly import EPSF files, while for others MetaPost's PostScript
+ output has to be converted to a different vector or even a bitmap
+ format first. In any case, as soon as PostScript graphics generated
+ by MetaPost are leaving the \TeX\ ecosystem, variable
+ \texttt{prologues} should be set to~3, so that all needed fonts are
+ embedded (as a subset).
+
+\item[\normalfont\itshape SVG output:] Converting font glyphs to paths
+ by setting variable \texttt{prologues} to~3 is currently the only
+ reliable way to export text objects to SVG.
+
+\item[\normalfont\itshape PNG output:] Variable \texttt{prologues} has
+ no effect in PNG output mode.
+
+\end{description}
+
+It is worth noting that the value of \ttt{prologues} has no effect on
+\MF\ fonts in your MetaPost files, i.\,e., MetaPost never embeds such
+fonts. Only output drivers, e.\,g., \ttt{dvips} or pdf\LaTeX\ will
+handle those.
+
+The details on how to include PostScript figures in a paper
+done in \TeX\ or troff are system-dependent. They can generally be found
+in manual pages and other on-line documentation, but have a look at
+section~\ref{mpimport} of this manual for some brief instructions that
+in many cases should work. The manual for the
+widely-used Dvips processor is in a file \ttt{dvips.texi}, included in
+most distributions, and is available online at
+\url{http://tug.org/texinfohtml/dvips.html}, among many other places and
+formats.
+
+\subsection{Font Map Files}
+\label{fontmap}
+
+If \ttt{prologues} is set to~2, any used fonts in the output file are
+automatically re-encoded, and the encoding vector file specified in
+the fontmap entry will be embedded in the output file. If
+\ttt{prologues} is set to~3, MetaPost will also attempt to include
+(a subset of) the used PostScript\index{PostScript!fonts} fonts. For
+this to work, it needs to acquire font map information.
+
+The code is based on the font library used by pdf\TeX. Following in the
+footsteps of pdf\TeX, there are two new associated primitives:
+\ttindex{fontmapfile}\label{Dfontmapfile} and
+\ttindex{fontmapline}\label{Dfontmapline}. Here is a simple example,
+specifying the map file for Latin Modern fonts in YandY (\LaTeX\ LY1)
+encoding:
+\begin{center}\begin{tabular}{l}
+\verb|prologues:=2;|\\
+\verb|fontmapfile "texnansi-lm.map";|\\
+\verb|beginfig(1);|\\
+\verb| draw "Helló, világ" infont "texnansi-lmr10";|\\
+\verb|endfig;|
+\end{tabular}\end{center}
+
+Using \ttt{fontmapline}, you can specify font mapping information
+inside the figure:
+\begin{center}\begin{tabular}{l}
+\verb|prologues:=2;|\\
+\verb|fontmapline "pplbo8r URWPalladioL-Bold "&ditto&|\\
+\verb| ".167 SlantFont"&ditto&" <8r.enc <uplb8a.pfb";|\\
+\verb|beginfig(1);|\\
+\verb| draw "Hello, world" infont "pplbo8r";|\\
+\verb|endfig;|
+\end{tabular}\end{center}
+This will attempt to reencode the PostScript font
+URWPalladioL-Bold\index{URWPalladioL-Bold}\index{Palatino}
+whose tfm file is pplbo8r.tfm. The encoding is found in the file
+8r.enc, and will be included into the output file.
+
+If the same example was run with \ttt{prologues:=3}, MetaPost would
+include a subset of the font that resides in uplb8a.pfb into the
+output. In this case, the subset of the font is reorganized so that it
+has the correct encoding internally, 8r.enc will not be embedded also.
+
+The argument to both commands has an optional flag character at the very
+beginning. This optional flag has the same meaning as in pdf\TeX:
+$$\begin{tabular}{|c|l|} \hline
+\multicolumn1{|c|}{Option}& \multicolumn1{c|}{Meaning}\\ \hline
+ + & extend the font list, but ignore duplicates \\
+ = & extend the font list, replacing duplicates \\
+ $-$ & remove all matching fonts from the font list \\
+\hline
+\end{tabular}
+$$
+Without any option, the current list will be completely replaced.
+
+If \ttt{prologues} is set to two or three, yet there are no
+\ttt{fontmapfile} statements, MetaPost will attempt to locate a
+default map file, with a preference to read {\tt mpost.map}. If that
+fails, it will also attempt either {\tt troff.map} or {\tt
+pdftex.map}, depending on whether or not troff mode is enabled. If
+\ttt{prologues} is set to~1, MetaPost attempts to read a file called
+{\tt psfonts.map}, regardless of any {\tt fontmapfile}
+statement. Again, this is for backward compatibility only.
+
+
+\subsection{The \texttt{infont} Operator}
+\label{Sinfont}
+
+Regardless of whether you use \TeX\ or troff, all the real work of
+adding text to pictures is done by a MetaPost primitive operator called
+{\tt infont}\index{infont?\texttt{infont}}. It is a \tdescr{primary
+ binop}\index{primary binop?\tdescr{primary binop}} that takes a
+\tdescr{string secondary} as its left argument and a \tdescr{string
+ primary} as its right argument. The left argument is text, and the
+right argument is a font name. The result of the operation is a
+\tdescr{picture secondary}, which can then be transformed in various
+ways. One possibility is enlargement by a given factor via the
+syntax\index{scaled?\texttt{scaled}}
+$$ \descr{picture secondary}\, \hbox{\tt scaled}\, \descr{numeric primary} $$
+Thus {\tt label("text",z0)} is equivalent to
+$$ \hbox{\tt label("text" infont defaultfont scaled defaultscale, z0)} $$
+
+If it is not convenient to use a string constant for the left argument of
+{\tt infont}, you can use\index{char?\texttt{char}}\label{Dchar}
+$$ {\tt char}\, \descr{numeric primary} $$
+to select a character based on its numeric position in the font.
+Thus
+$$ \hbox{\tt char(n+64) infont "ptmr8r"} $$
+is a picture containing character {\tt n+64} of the font \ttt{ptmr8r},
+which is a typical \TeX\ way to refer to Times-Roman. See p.\
+\pageref{fontname} for further discussion.
+
+Bare MetaPost does not do any kind of input reencoding, so when
+you use {\tt infont} string for labels (instead of {\tt btex} \ldots\
+{\tt etex}), the string has to be specified in the font encoding.
+
+
+\subsection{Measuring Text}
+\label{meas}
+
+MetaPost makes readily available the physical dimensions\index{size} of
+pictures generated by the {\tt infont} operator. There are unary
+operators {\tt
+llcorner}\index{llcorner?\texttt{llcorner}}\label{Dcornop}, {\tt
+lrcorner}\index{lrcorner?\texttt{lrcorner}}, {\tt
+urcorner}\index{urcorner?\texttt{urcorner}}, {\tt
+ulcorner}\index{ulcorner?\texttt{ulcorner}}, and {\tt
+center}\index{center?\texttt{center}}\label{Dcenter} that take a \tdescr{picture
+primary} and return the corners of its ``bounding box'' as illustrated
+in Figure~\ref{bbox}. The {\tt center} operator also accepts
+\tdescr{path primary} and \tdescr{pen primary} operands. In MetaPost
+Version 0.30 and higher, {\tt llcorner}, {\tt lrcorner}, etc. accept
+all three argument types as well.
+
+The argument type restrictions on the corner operators are not very
+important because their main purpose is to allow {\tt label} and {\tt
+dotlabel} statements to center their text properly. The predefined
+macro\index{bbox?\texttt{bbox}}\label{Dbbox}
+$$ {\tt bbox}\, \descr{picture primary} $$
+finds a rectangular path that represents the bounding box of a given picture.
+If {\tt p} is a picture, {\tt bbox p} is equivalent to
+$$\begin{verbatim}
+(llcorner p--lrcorner p--urcorner p--ulcorner p--cycle)
+\end{verbatim}
+$$
+except that it allows for a small amount of extra space around {\tt p}
+as specified by the internal variable\index{internal
+variables}\index{variables!internal} {\tt
+bboxmargin}\index{bboxmargin?\texttt{bboxmargin}}\label{Dbbmargin}.
+
+\begin{figure}[htp]
+$$ \includegraphics{mpman-20.mps} $$
+\caption{A bounding box and its corner points.}
+\label{bbox}
+\end{figure}
+
+Note that MetaPost computes the bounding box of a {\tt
+btex}\index{btex?\texttt{btex}} \ldots\ {\tt
+etex}\index{etex?\texttt{etex}} picture just the way
+\TeX\index{TeX?\TeX} does. This is quite natural, but it has certain
+implications in view of the fact that \TeX\ has features like
+{\tt\string\strut}\index{strut?{\tt\string\strut}} and
+{\tt\string\rlap}\index{rlap?{\tt\string\rlap}} that allow \TeX\ users
+to lie about the dimensions of a box.
+
+When \TeX\ commands that lie about the dimensions of a box are
+translated in to low-level MetaPost code, a {\tt
+setbounds}\index{setbounds?\texttt{setbounds}}\label{Dsetbnd} statement
+does the lying:\index{picture variable?\tdescr{picture variable}}
+$$ {\tt setbounds}\, \descr{picture variable}\, {\tt to}\, \descr{path expression}
+$$
+makes the \tdescr{picture variable} behave as if its bounding box were
+the same as the given path. The path has to be a cycle, i.e., it must
+be a closed path. To get the true bounding box of such a
+picture, assign a positive value to the internal variable\index{internal
+variables}\index{variables!internal} {\tt
+truecorners}\index{truecorners?\texttt{truecorners}}\label{Dtruecorn}:\footnote{The
+{\tt setbounds} and {\tt truecorners} features are only found in
+MetaPost version 0.30 and higher.} i.e.,
+$$ \hbox{\verb|show urcorner btex $\bullet$\rlap{ A} etex|} $$
+produces ``\verb|>> (4.9813,6.8078)|'' while
+$$ \hbox{\verb|truecorners:=1; show urcorner btex $\bullet$\rlap{ A} etex|} $$
+produces ``\verb|>> (15.7742,6.8078)|.''
+
+
+\section{Advanced Graphics}
+\label{adv.gr}
+
+All the examples in the previous sections have been simple line drawings
+with labels added. This section describes shading and tools for
+generating not-so-simple line drawings. Shading is done with the {\tt
+fill}\index{fill?\texttt{fill}}\label{Dfill} statement. In its simplest
+form, the {\tt fill} statement requires a \tdescr{path expression} that
+gives the boundary of the region to be filled. In the syntax
+$$ {\tt fill}\, \descr{path expression} $$
+the argument should be a cyclic path, i.e., a path that describes a
+closed curve via the \verb|..cycle| or \verb|--cycle| notation. For
+example, the {\tt fill} statement in Figure~\ref{fig20} builds a closed
+path by extending the roughly semicircular path~{\tt p}. This path has
+a counter-clockwise orientation, but that does not matter because the
+{\tt fill} statement uses PostScript's\index{PostScript} non-zero
+winding\index{winding number} number rule\index{non-zero fill
+ rule}\index{fill rule!non-zero}\index{PostScript!fill
+ rule}~\cite{ad:red2}.
+
+\begin{figure}[htp]
+$$ \begin{verbatim}
+beginfig(21);
+path p;
+p = (-1cm,0)..(0,-1cm)..(1cm,0);
+fill p{up}..(0,0){-1,-2}..{up}cycle;
+draw p..(0,1cm)..cycle;
+endfig;
+\end{verbatim}
+\qquad \mathcenter{\includegraphics{mpman-21.mps}}
+$$
+\caption{MetaPost code and the corresponding output.}
+\label{fig20}
+\end{figure}
+
+The general {\tt fill} statement\index{withcolor?\texttt{withcolor}}\label{Dwithcolor}
+$$ {\tt fill}\, \descr{path expression}\,
+ {\tt withcolor}\, \descr{color expression}
+$$
+specifies a shade of gray or (if you have a color printer) some
+rainbow color. The $\descr{color expression}$ can have five possible
+values, mapping to four possible color models:
+
+$$
+\begin{tabular}{ll}
+Actual input & Remapped meaning\\\hline
+{\tt withcolor} $\descr{rgbcolor} c$ & withrgbcolor\index{withrgbcolor?\texttt{withrgbcolor}}\label{Dwithrgbcolor} $c$\\
+{\tt withcolor} $\descr{cmykcolor} c$ & withcmykcolor\index{withcmykcolor?\texttt{withcmykcolor}}\label{Dwithcmykcolor} $c$\\
+{\tt withcolor} $\descr{numeric} c$ & withgreyscale\index{withgreyscale?\texttt{withgreyscale}}\label{Dwithgreyscale} $c$\\
+{\tt withcolor} $\descr{false}$ & withoutcolor\index{withoutcolor?\texttt{withoutcolor}}\label{Dwithoutcolor} \\
+{\tt withcolor} $\descr{true}$ & $\descr{current default color model}$\\
+\end{tabular}
+$$
+
+For the specific color models, there are also:
+$$ {\tt fill}\, \descr{path expression}\,
+ {\tt withrgbcolor}\, \descr{rgbcolor expression}
+$$
+$$ {\tt fill}\, \descr{path expression}\,
+ {\tt withcmykcolor}\, \descr{cmykcolor expression}
+$$
+$$ {\tt fill}\, \descr{path expression}\,
+ {\tt withgreyscale}\, \descr{numeric}
+$$
+$$ {\tt fill}\, \descr{path expression}\,
+ {\tt withoutcolor}
+$$
+
+An image object cannot have more then one color model, the last
+\ttt{withcolor}, \ttt{withrgbcolor}, \ttt{withcmykcolor},
+\ttt{withgreyscale} or \ttt{withoutcolor} specification sets the color
+model for any particular object.
+
+The model \ttt{withoutcolor} needs a bit more explanation: selecting
+this model means that MetaPost will not write a color selection
+statement to the PostScript output file for this object.
+
+The `current default' color model can be set up using the internal
+variable \ttindex{defaultcolormodel}\label{Ddefaultcolormodel}.
+Table~\ref{dfltcmod} lists the valid values.
+\begin{table}
+\centering
+\begin{tabular}{|c|l|}
+\hline
+Value & Color model\\\hline
+1 & no model\\
+3 & greyscale\\
+5 & rgb (default)\\
+7 & cmyk\\
+\hline
+\end{tabular}
+\caption{Supported color models.}
+\label{dfltcmod}
+\end{table}
+
+
+Figure~\ref{fig21} illustrates several applications of the fill command
+to fill areas with shades of gray. The paths involved are intersecting
+circles {\tt a} and {\tt b} and a path {\tt ab} that bounds the region
+inside both circles. Circles {\tt a} and {\tt b} are derived from {\tt
+ fullcircle}. Path~{\tt ab} is then initialized using a predefined
+macro {\tt buildcycle} that will be discussed shortly.
+
+\begin{figure}[htp]
+$$ \begin{verbatim}
+beginfig(22);
+path a, b, aa, ab;
+a = fullcircle scaled 2cm;
+b = a shifted (0,1cm);
+aa = halfcircle scaled 2cm;
+ab = buildcycle(aa, b);
+picture pa, pb;
+pa = thelabel(btex $A$ etex, (0,-.5cm));
+pb = thelabel(btex $B$ etex, (0,1.5cm));
+fill a withcolor .7white;
+fill b withcolor .7white;
+fill ab withcolor .4white;
+unfill bbox pa;
+draw pa;
+unfill bbox pb;
+draw pb;
+label.lft(btex $U$ etex, (-1cm,.5cm));
+draw bbox currentpicture;
+endfig;
+\end{verbatim}
+\qquad \mathcenter{\includegraphics{mpman-22.mps}}
+$$
+\caption{MetaPost code and the corresponding output.}
+\index{fullcircle?\texttt{fullcircle}}\index{halfcircle?\texttt{halfcircle}}\index{buildcycle?\texttt{buildcycle}}
+\label{fig21}
+\end{figure}
+
+Filling circle {\tt a} with the light gray color {\tt .7white} and then
+doing the same with circle {\tt b} doubly fills the region where the
+disks overlap. The rule is that each {\tt fill} statement assigns the
+given color to all points in the region covered, wiping out whatever was
+there previously including lines and text as well as filled regions.
+Thus it is important to give {\tt fill} commands in the right order. In
+the above example, the overlap region gets the same color twice, leaving
+it light gray after the first two {\tt fill} statements. The third fill
+statement assigns the darker color {\tt .4white} to the overlap region.
+
+At this point the circles and the overlap region have their final colors
+but there are no cutouts for the labels. The cutouts are achieved by
+the {\tt unfill}\index{unfill?\texttt{unfill}}\label{Dunfill} statements
+that effectively erase\index{erasing} the regions bounded by {\tt bbox
+pa}\index{bbox?\texttt{bbox}} and {\tt bbox pb}. More precisely, {\tt
+unfill} is shorthand for filling {\tt withcolor background}, where {\tt
+background} is normally equal to {\tt white} as is appropriate for
+printing on white paper. If necessary, you can assign a new color value
+to {\tt
+background}\index{background?\texttt{background}}\label{Dbground}.
+
+The labels need to be stored in pictures {\tt pa} and {\tt pb} to allow
+for measuring their bounding box before actually drawing them. The
+macro {\tt thelabel}\index{thelabel?\texttt{thelabel}} creates such
+pictures and shifts them into position so that they are ready to draw.
+Using the resulting pictures in {\tt draw} statements of the
+form\index{draw?\texttt{draw}}
+$$ {\tt draw}\, \descr{picture expression} $$
+adds them to {\tt currentpicture}\index{currentpicture?\texttt{currentpicture}}
+so that they overwrite a portion of what has
+already been drawn. In Figure~\ref{fig21} just the white rectangles produced by
+{\tt unfill} get overwritten.
+
+\subsection{Building Cycles}
+\label{buildcy}
+
+The {\tt buildcycle}\index{buildcycle?\texttt{buildcycle}} command
+constructs paths for use with the {\tt fill} or {\tt unfill} macros.
+When given two or more paths such as {\tt aa} and {\tt b}, the {\tt
+buildcycle} macro tries to piece them together so as to form a cyclic
+path. In this case path {\tt aa} is a semicircle that starts just to
+the right of the intersection with path {\tt b}, then passes through
+{\tt b} and ends just outside the circle on the left as shown in
+Figure~\ref{fig22}a.
+
+Figure~\ref{fig22}b shows how {\tt buildcycle} forms a closed cycle from
+the pieces of paths {\tt aa} and {\tt b}. The {\tt buildcycle} macro
+detects the two intersections\index{intersections} labeled 1 and 2 in
+Figure~\ref{fig22}b. Then it constructs the cyclic path shown in bold
+in the figure by going forward along path {\tt aa} from intersection~1
+to intersection~2 and then forward around the counter-clockwise path
+{\tt b} back to intersection~1. It turns out that {\tt buildcycle(a,b)}
+would have produced the same result, but the reasoning behind this is a
+little confusing.
+
+
+\begin{figure}[htp]
+$$ {\includegraphics{mpman-123.mps} \atop (a)}
+ \qquad {\includegraphics{mpman-223.mps} \atop (b)}
+$$
+\caption[A demonstration of cycle building]
+ {(a)~The semicircular path~{\tt aa}
+ with a dashed line marking path {\tt b}; (b)~paths~{\tt aa} and {\tt b}
+ with the portions selected by {\tt buildcycle} shown by heavy lines.}
+\label{fig22}
+\end{figure}
+
+It is a easier to use the {\tt buildcycle} macro in situations like
+Figure~\ref{fig23} where there are more than two path arguments and each
+pair of consecutive paths has a unique intersection. For instance, the
+line~{\tt q0.5} and the curve~{\tt p2} intersect only at point~$P$; and
+the curve {\tt p2} and the line~{\tt q1.5} intersect only at point~$Q$.
+In fact, each of the points $P$, $Q$, $R$, $S$ is a unique intersection,
+and the result of\index{buildcycle?\texttt{buildcycle}}
+$$ \hbox{\tt buildcycle(q0.5, p2, q1.5, p4)} $$
+takes {\tt q0.5} from $S$ to~$P$, then {\tt p2} from $P$ to~$Q$, then
+{\tt q1.5} from $Q$ to~$R$, and finally {\tt p4} from $R$ back to~$S$.
+An examination of the MetaPost code for Figure~\ref{fig23} reveals that
+you have to go backwards along {\tt p2} in order to get from $P$ to~$Q$.
+This works perfectly well as long as the
+intersection\index{intersection} points are uniquely defined but it can
+cause unexpected results when pairs of paths intersect more than once.
+
+\begin{figure}[htp]
+$$ \begin{verbatim}
+beginfig(24);
+h=2in; w=2.7in;
+path p[], q[], pp;
+for i=2 upto 4: ii:=i**2;
+ p[i] = (w/ii,h){1,-ii}...(w/i,h/i)...(w,h/ii){ii,-1};
+endfor
+q0.5 = (0,0)--(w,0.5h);
+q1.5 = (0,0)--(w/1.5,h);
+pp = buildcycle(q0.5, p2, q1.5, p4);
+fill pp withcolor .7white;
+z0=center pp;
+picture lab; lab=thelabel(btex $f>0$ etex, z0);
+unfill bbox lab; draw lab;
+draw q0.5; draw p2; draw q1.5; draw p4;
+dotlabel.top(btex $P$ etex, p2 intersectionpoint q0.5);
+dotlabel.rt(btex $Q$ etex, p2 intersectionpoint q1.5);
+dotlabel.lft(btex $R$ etex, p4 intersectionpoint q1.5);
+dotlabel.bot(btex $S$ etex, p4 intersectionpoint q0.5);
+endfig;
+\end{verbatim}
+\atop \mathcenter{\includegraphics{mpman-24.mps}}
+$$
+\caption{MetaPost code and the corresponding output.}
+\label{fig23}
+\end{figure}
+
+The general rule for the {\tt buildcycle} macro is that
+$$ \hbox{\tt buildcycle(}p_1\hbox{\tt,}\, p_2\hbox{\tt,}\,
+ p_3\hbox{\tt,}\, \ldots \hbox{\tt,} p_k \hbox{\tt )}
+$$
+chooses the intersection between each $p_i$ and $p_{i+1}$ to be as late
+as possible on $p_i$ and as early as possible on $p_{i+1}$. There is no
+simple rule for resolving conflicts between these two goals, so you
+should avoid cases where one intersection point occurs later on $p_i$
+and another intersection\index{intersection} point occurs earlier on
+$p_{i+1}$.
+
+The preference for intersections as late as possible on $p_i$ and as
+early as possible on $p_{i+1}$ leads to ambiguity resolution in favor of
+forward-going subpaths. For cyclic paths such as path~{\tt b} in
+Figure~\ref{fig22} ``early'' and ``late'' are relative to a start/finish
+point which is where you get back to when you say ``{\tt ..cycle}''.
+For the path~{\tt b}, this turns out to be the rightmost point on the
+circle.
+
+A more direct way to deal with path intersections is via the
+\tdescr{secondary binop}\index{secondary binop?\tdescr{secondary binop}}
+{\tt
+intersection\-point}\index{intersectionpoint?\texttt{intersectionpoint}}\label{Disecpt}
+that finds the points $P$, $Q$, $R$, and~$S$ in Figure~\ref{fig23}.
+This macro finds a point where two given paths intersect. If there is
+more than one intersection point, it just chooses one; if there is no
+intersection, the macro generates an error message.
+
+\subsection{Dealing with Paths Parametrically}
+
+The {\tt
+intersectionpoint}\index{intersectionpoint?\texttt{intersectionpoint}}
+macro is based on a primitive operation called {\tt
+intersectiontimes}\index{intersectiontimes?\texttt{intersectiontimes}}\label{Disectt}.
+This \tdescr{secondary binop} is one of several operations that deal
+with paths parametrically. It locates an intersection between two paths
+by giving the ``time'' parameter on each path. This refers to the
+parameterization scheme from Section~\ref{curves} that described paths
+as piecewise cubic curves $\bigl(X(t),Y(t)\bigr)$ where $t$ ranges from
+zero to the number of curve segments. In other words, when a path is
+specified as passing through a sequence of points, where $t=0$ at the
+first point, then $t=1$ at the next, and $t=2$ at the next, etc. The
+result of
+$$ \hbox{\tt a intersectiontimes b} $$
+is $(-1,-1)$ if there is no intersection; otherwise you get
+a pair $(t_a,t_b)$, where $t_a$ is a time on path {\tt a} when it intersects
+path~{\tt b}, and $t_b$ is the corresponding time on path~{\tt b}.
+
+For example, suppose path~{\tt a} is denoted by the thin line in
+Figure~\ref{fig24} and path~{\tt b} is denoted by the thicker line. If
+the labels indicate time values on the paths, the pair of time values
+computed by
+$$ \hbox{\tt a intersectiontimes b} $$
+must be one of
+$$ (0.25,1.77),\ (0.75,1.40), {\rm or}\ (2.58,0.24), $$
+depending on which of the three intersection points is chosen by the
+MetaPost interpreter. The exact rules for choosing among multiple
+intersection points are a little complicated, but it turns out that you
+get the time values $(0.25,1.77)$ in this example. Smaller time values
+are preferred over larger ones so that $(t_a,t_b)$ is preferred to
+$(t'_a,t'_b)$ whenever $t_a<t'_a$ and $t_b<t'_b$. When no single
+alternative minimizes both the $t_a$ and $t_b$ components the $t_a$
+component tends to get priority, but the rules get more complicated when
+there are no integers between $t_a$ and $t'_a$\index{intersection}.
+(For more details, see {\sl The \MF book} \cite[Chapter 14]{kn:c}).
+
+\begin{figure}[htp]
+$$ \includegraphics{mpman-25.mps} $$
+\caption{Two intersecting paths with time values marked on each path.}
+\label{fig24}
+\end{figure}
+
+The {\tt intersectiontimes} operator is more flexible than {\tt
+intersectionpoint} because there are a number of things that can be done
+with time values on a path. One of the most important is just to ask
+``where is path {\tt p} at time {\tt t}?'' The construction\index{point
+of?\texttt{point of}}\label{Dpntof}
+$$ {\tt point}\, \descr{numeric expression}\, {\tt of}\, \descr{path primary} $$
+answers this question. If the \tdescr{numeric expression} is less than
+zero or greater than the time value assigned to the last point on the
+path, the {\tt point of} construction normally yields an endpoint of the
+path. Hence, it is common to use the predefined constant {\tt
+infinity}\index{infinity?\texttt{infinity}}\label{Dinf} (equal to
+4095.99998) as the \tdescr{numeric expression} in a {\tt point of}
+construction when dealing with the end of a path.
+
+Such ``infinite'' time values do not work for a cyclic path, since time
+values outside of the normal range can be handled by modular arithmetic
+in that case; i.e., a cyclic path~{\tt p} through points $z_0$, $z_1$,
+$z_2$, \ldots, $z_{n-1}$ has the normal parameter range $0\le t<n$, but
+$$ \hbox{\tt point t of p} $$
+can be computed for any~$t$ by first reducing $t$ modulo~$n$. If the
+modulus~$n$ is not readily
+available,\index{length?\texttt{length}}\label{Dlength}
+$$ {\tt length}\, \descr{path primary} $$
+gives the integer value of the upper limit of the normal time parameter
+range for the specified path.
+
+MetaPost uses the same correspondence between time values and points on
+a path to evaluate the {\tt
+subpath}\index{subpath?\texttt{subpath}}\label{Dsubpth} operator. The
+syntax for this operator is
+$$ {\tt subpath}\, \descr{pair expression}\, {\tt of}\, \descr{path primary} $$
+If the value of the \tdescr{pair expression} is $(t_1,t_2)$ and the
+\tdescr{path primary} is $p$, the result is a path that follows $p$ from
+{\tt point $t_1$ of $p$} to {\tt point $t_2$ of $p$}. If $t_2<t_1$, the
+subpath runs backwards along~$p$.
+
+An important operation based on the {\tt subpath} operator is the
+\tdescr{tertiary binop}\index{tertiary binop?\tdescr{tertiary binop}}
+{\tt cutbefore}\index{cutbefore?\texttt{cutbefore}}\label{Dcutb}. For
+intersecting paths $p_1$ and $p_2$,
+$$ p_1\ {\tt cutbefore}\ p_2 $$
+is equivalent to
+$$ \hbox{\tt subpath (xpart($p_1$ intersectiontimes $p_2$), length $p_1$) of $p_1$}
+$$
+except that it also sets the path variable {\tt
+cuttings}\index{cuttings?\texttt{cuttings}}\label{Dcuttings} to the
+portion of $p_1$ that gets cut off. In other words, {\tt cutbefore}
+returns its first argument with the part before the intersection cut
+off. With multiple intersections, it tries to cut off as little as
+possible. If the paths do not intersect, {\tt cutbefore} returns its
+first argument.
+
+There is also an analogous \tdescr{tertiary binop}\index{tertiary
+binop?\tdescr{tertiary binop}} called {\tt
+cutafter}\index{cutafter?\texttt{cutafter}}\label{Dcuta} that works by
+applying {\tt cutbefore} with time reversed along its first argument.
+Thus
+$$ p_1\ {\tt cutafter}\ p_2 $$
+tries to cut off the part of $p_1$ after its last intersection with $p_2$.
+
+The control points of a path can be requested by the two operators
+\index{precontrol of?\texttt{precontrol of}}
+\index{postcontrol of?\texttt{postcontrol of}}
+\label{Dprepostctrl}
+\begin{eqnarray*}
+ {\tt precontrol}\, \descr{numeric expression}\, {\tt of}\, \descr{path primary},\\
+ {\tt postcontrol}\, \descr{numeric expression}\, {\tt of}\, \descr{path primary}.
+\end{eqnarray*}
+
+For integer time values~$t$, these operators return the control points
+before and after a cardinal point of a path. A segment
+$z_{t-1}\verb|..|z_t$ of a path~$p$ has therefore control points
+$$ {\tt postcontrol}\ t-1\ {\tt of}\ p
+$$
+and
+$$ {\tt precontrol}\ t\ {\tt of}\ p.
+$$
+
+For decimal time values, {\tt precontrol of} returns the last control
+point of sub-path $(0, t)$ and {\tt postcontrol of} returns the first
+control point of sub-path $(t, \infty)$ of a path. In other words, the
+control points at fractional time values correspond to a virtual
+cardinal point inserted at the given time value without modifying path
+shape.
+
+Another operator\index{direction of?\texttt{direction of}}\label{Ddirof}
+$$ {\tt direction}\, \descr{numeric expression}\, {\tt of}\, \descr{path primary}
+$$
+finds a vector in the direction of the \tdescr{path primary}. This is
+defined for any time value analogously to the {\tt point of}
+construction. The resulting direction vector has the correct
+orientation and a somewhat arbitrary magnitude. Combining {\tt point
+of} and {\tt direction of} constructions yields the equation for a
+tangent line as illustrated in Figure~\ref{fig25}.
+
+\begin{figure}[htp]
+$$ \begin{verbatim}
+beginfig(26);
+numeric scf, #, t[];
+3.2scf = 2.4in;
+path fun;
+# = .1; % Keep the function single-valued
+fun = ((0,-1#)..(1,.5#){right}..(1.9,.2#){right}..{curl .1}(3.2,2#))
+ yscaled(1/#) scaled scf;
+x1 = 2.5scf;
+for i=1 upto 2:
+ (t[i],whatever) =
+ fun intersectiontimes ((x[i],-infinity)--(x[i],infinity));
+ z[i] = point t[i] of fun;
+ z[i]-(x[i+1],0) = whatever*direction t[i] of fun;
+ draw (x[i],0)--z[i]--(x[i+1],0);
+ fill fullcircle scaled 3bp shifted z[i];
+endfor
+label.bot(btex $x_1$ etex, (x1,0));
+label.bot(btex $x_2$ etex, (x2,0));
+label.bot(btex $x_3$ etex, (x3,0));
+draw (0,0)--(3.2scf,0);
+pickup pencircle scaled 1pt;
+draw fun;
+endfig;
+\end{verbatim}
+\atop \includegraphics{mpman-26.mps}
+$$
+\caption{MetaPost code and the resulting figure}
+\label{fig25}
+\end{figure}
+
+If you know a slope and you want to find a point on a curve where the
+tangent line has that slope, the {\tt directiontime}\index{directiontime
+of?\texttt{directiontime of}}\label{Ddtimof} operator inverts the {\tt
+direction of} operation. Given a direction vector and a path,
+$$ {\tt directiontime}\, \descr{pair expression}\, {\tt of}\,
+ \descr{path primary}
+$$
+returns a numeric value that gives the first time~$t$ when the path has
+the indicated direction. (If there is no such time, the result is
+$-1$). For example, if {\tt a} is the path drawn as a thin curve in
+Figure~\ref{fig24}, {\tt directiontime (1,1) of a} returns 0.2084.
+
+There is also an predefined macro \index{directionpoint
+of?\texttt{directionpoint of}}\label{Ddpntof}
+$$ {\tt directionpoint}\, \descr{pair expression}\, {\tt of}\,
+ \descr{path primary}
+$$
+that finds the first point on a path where a given direction is achieved. The
+{\tt directionpoint} macro produces an error message if the direction does not
+occur on the path.
+
+Operators {\tt
+arclength}\index{arclength?\texttt{arclength}}\label{Darclng} and {\tt
+arctime of}\index{arctime of?\texttt{arctime of}}\label{Darctim} relate
+the ``time'' on a path to the more familiar concept of arc
+length.\index{arc length}\footnote{The {\tt arclength} and {\tt arctime}
+operators are only found in MetaPost version 0.50 and higher.} The
+expression
+$$ \hbox{{\tt arclength} \tdescr{path primary}} $$
+gives the arc length of a path. If {\tt p} is a path and {\tt a} is a number
+between 0 and {\tt arclength p},
+$$ \hbox{\tt arctime a of p} $$
+gives the time~{\tt t} such that
+$$ \hbox{\tt arclength subpath (0,t) of p} = {\tt a}. $$
+
+The operator {\tt
+ envelope}\index{envelope?\texttt{envelope}}\label{Denvelop} %
+returns the envelope of a path {\tt p} drawn with a polygonal pen,
+and returns an error if the pen is not polygonal.
+Figure~\ref{fig261} shows the envelope of an approximation of an elliptical pen.
+
+\begin{figure}[htp]
+$$ \begin{verbatim}
+beginfig(261);
+path p[] ;
+pen mypen ;
+pen mypenC;
+numeric L ;
+numeric S ;
+L:=10;
+Sa:=1;
+Sb:=2;
+Rot=32;
+p[-1] := ( (Sa*cosd(0),Sb*sind(0)) for i=1 upto L-1:
+ -- (Sa*cosd(i/L*360), Sb*sind(i/L*360)) endfor -- cycle ) rotated Rot;
+mypen := makepen(p[-1]) ;
+mypenC:= (pencircle xscaled 2Sa yscaled 2Sb) rotated Rot;
+p0 := (0,0){down} .. {up} (100,0) ;
+p1 := envelope mypen of p0 ;
+draw p1 withcolor black withpen pencircle scaled 0.2pt ;
+draw p0 withcolor 0.8white withpen mypenC;
+for t=1 upto length(p1):
+ draw (point t of p1) withpen pencircle scaled 0.8pt;
+endfor;
+endfig;
+\end{verbatim}
+\atop \includegraphics[width=0.9\textwidth]{mpman-261.mps}
+$$
+\caption{Example of envelope}
+\label{fig261}
+\end{figure}
+
+
+
+\subsection{Affine Transformations}
+\label{transsec}
+\index{transform type}
+
+Note how path {\tt fun} in Figure~\ref{fig25} is first constructed as
+$$ \hbox{\verb|(0,-.1)..(1,.05){right}..(1.9,.02){right}..{curl .1}(3.2,.2)|} $$
+and then the {\tt yscaled}\index{yscaled?\texttt{yscaled}} and {\tt
+scaled}\index{scaled?\texttt{scaled}} operators are used to adjust the
+shape and size of the path. As the name suggests, an expression
+involving ``{\tt yscaled 10}'' multiplies $y$ coordinates by ten so that
+every point $(x,y)$ on the original path corresponds to a point
+$(x,10y)$ on the transformed path.
+
+Including {\tt scaled} and {\tt yscaled}, there are seven transformation
+operators that take a numeric or pair
+argument:\index{shifted?\texttt{shifted}}%
+\index{rotated?\texttt{rotated}}\index{slanted?\texttt{slanted}}\index{scaled?\texttt{scaled}}\index{xscaled?\texttt{xscaled}}%
+\index{yscaled?\texttt{yscaled}}\index{zscaled?\texttt{zscaled}}\label{Dtranop}
+\begin{eqnarray*}
+ (x,y){\tt\ shifted\ }(a,b) &=& (x+a,\, y+b); \\
+ (x,y){\tt\ rotated\ }\theta &=& (x\cos\theta-y\sin\theta,\,
+ x\sin\theta+y\cos\theta); \\
+ (x,y){\tt\ slanted\ }a &=& (x+ay,\, y); \\
+ (x,y){\tt\ scaled\ }a &=& (ax,\, ay); \\
+ (x,y){\tt\ xscaled\ }a &=& (ax,\, y); \\
+ (x,y){\tt\ yscaled\ }a &=& (x,\, ay); \\
+ (x,y){\tt\ zscaled\ }(a,b) &=& (ax-by,\, bx+ay).
+\end{eqnarray*}
+Most of these operations are self-explanatory except for {\tt zscaled}
+which can be thought of as multiplication of complex numbers. The
+effect of {\tt zscaled} $(a,b)$ is to rotate and scale so as to map
+$(1,0)$ into $(a,b)$. The effect of {\tt rotated}~$\theta$ is rotate
+$\theta$ degrees counter-clockwise.
+
+Any combination of shifting, rotating, slanting, etc.\ is an affine
+transformation, the net effect of which is to transform any pair $(x,y)$
+into
+$$ (t_x+t_{xx}x+t_{xy}y,\, t_y+t_{yx}x+t_{yy}y), $$
+for some sextuple $(t_x,t_y,t_{xx},t_{xy},t_{yx},t_{yy})$. This
+information can be stored in a variable of type transform so that {\tt
+transformed T}\index{transformed?\texttt{transformed}}\label{Dtrfrmd}
+might be equivalent to
+$$ \hbox{\tt xscaled -1 rotated 90 shifted (1,1)} $$
+if {\tt T} is an appropriate transform variable. The
+transform~{\tt T} could then be initialized with an
+expression of type transform as follows:
+$$ \begin{verbatim}
+transform T;
+T = identity xscaled -1 rotated 90 shifted (1,1);
+\end{verbatim}
+$$
+As this example indicates, transform expressions can be built up by
+applying transformation operators to other transforms. The predefined
+transformation {\tt
+identity}\index{identity?\texttt{identity}}\label{Dident} is a useful
+starting point for this process. This can be illustrated by
+paraphrasing the above equation for {\tt T} into English: ``{\tt T}
+should be the transform obtained by doing whatever {\tt identity}
+does. Then scaling $x$~coordinates by $-1$, rotating $90^\circ$, and
+shifting by $(1,1)$.'' This works because {\tt identity} is the
+identity transformation which does nothing; i.e., {\tt transformed
+identity} is a no-op.
+
+The syntax for transform expressions and transformation operators is given in
+Figure~\ref{sytrans}. It includes two more options for
+\tdescr{transformer}:\index{reflectedabout?\texttt{reflectedabout}}
+$$ \hbox{\tt reflectedabout(}p, q\hbox{\tt )} $$
+reflects about the line defined by points $p$ and $q$;
+and\index{rotatedaround?\texttt{rotatedaround}}
+$$ \hbox{\tt rotatedaround(}p,\theta\hbox{\tt )} $$
+rotates $\theta$ degrees counter-clockwise around point $p$. For example,
+the equation for initializing transform~{\tt T} could have been
+$$ \hbox{\tt T = identity reflectedabout((2,0), (0,2))}. $$
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{pair secondary} \rightarrow
+ \descr{pair secondary} \descr{transformer}$\\
+$\tt \descr{path secondary} \rightarrow
+ \descr{path secondary} \descr{transformer}$\\
+$\tt \descr{picture secondary} \rightarrow
+ \descr{picture secondary} \descr{transformer}$\\
+$\tt \descr{pen secondary} \rightarrow
+ \descr{pen secondary} \descr{transformer}$\\
+$\tt \descr{transform secondary} \rightarrow
+ \descr{transform secondary} \descr{transformer}$\\[6pt]
+$\tt \descr{transformer} \rightarrow rotated \descr{numeric primary}$\\
+$\tt \qquad \;|\; scaled \descr{numeric primary}$\\
+$\tt \qquad \;|\; shifted \descr{pair primary}$\\
+$\tt \qquad \;|\; slanted \descr{numeric primary}$\\
+$\tt \qquad \;|\; transformed \descr{transform primary}$\\
+$\tt \qquad \;|\; xscaled \descr{numeric primary}$\\
+$\tt \qquad \;|\; yscaled \descr{numeric primary}$\\
+$\tt \qquad \;|\; zscaled \descr{pair primary}$\\
+$\tt \qquad \;|\; reflectedabout\hbox{\tt (}\descr{pair expression}
+ \hbox{\tt ,}\descr{pair expression}\hbox{\tt )}$\\
+$\tt \qquad \;|\; rotatedaround\hbox{\tt (}\descr{pair expression}
+ \hbox{\tt ,}\descr{numeric expression}\hbox{\tt )}$
+\end{ctabbing}
+\caption{The syntax for transforms and related operators}
+\label{sytrans}
+\end{figure}
+
+There is also a unary operator {\tt
+inverse}\index{inverse?\texttt{inverse}}\label{Dinv} that takes a
+transform and finds another transform that undoes the effect of the
+first transform. Thus if
+$$ p = q{\tt\ transformed\ }T $$
+then
+$$ q = p{\tt\ transformed\ inverse\ }T. $$
+
+It is not legal to take the {\tt inverse} of an
+unknown transform\index{transformation!unknown} but we
+have already seen that you can say
+$$ \hbox{\tt T = } \descr{transform expression} $$
+when {\tt T} has not been given a value yet. It is also possible to
+apply an unknown transform to a known pair or transform and use the
+result in a linear equation. Three such equations are sufficient to
+determine a transform. Thus the equations
+$$ \begin{verbatim}
+(0,1) transformed T' = (3,4);
+(1,1) transformed T' = (7,1);
+(1,0) transformed T' = (4,-3);
+\end{verbatim}
+$$
+allow MetaPost to determine that the transform {\tt T'} is a combination of
+rotation and scaling with
+$$\openup\jot
+ \tabskip=0pt plus 1fil
+ \halign to\displaywidth{\tabskip=0pt
+ \hfil$\displaystyle{#}$& $\displaystyle{{}#}$\hfil \qquad&
+ \hfil$\displaystyle{#}$& $\displaystyle{{}#}$\hfil
+ \tabskip=0pt plus 1fil\cr
+\noalign{\vskip-\jot}
+ t_{xx}&=4,& t_{yx}&=-3,\cr
+ t_{yx}&=3,& t_{yy}&=4,\cr
+ t_x&=0,& t_y&=0.\cr}
+$$
+
+Equations involving an unknown transform are treated as linear equations
+in the six parameters that define the transform. These six parameters
+can also be referred to directly
+as\index{xpart?\texttt{xpart}}\index{ypart?\texttt{ypart}}\index{xxpart?\texttt{xxpart}}%
+\index{xypart?\texttt{xypart}}\index{yxpart?\texttt{yxpart}}\index{yypart?\texttt{yypart}}\label{Dtrprt}
+$$ {\tt xpart\ T},\ {\tt ypart\ T},\ {\tt xxpart\ T},\ {\tt xypart\ T},\
+ {\tt yxpart\ T},\ {\tt yypart\ T},
+$$
+where {\tt T} is a transform. For instance, Figure~\ref{fig27} uses the
+equations
+$$ \hbox{\tt xxpart T=yypart T; yxpart T=-xypart T} $$
+to specify that {\tt T} is shape preserving; i.e., it is a combination of
+rotating, shifting, and uniform scaling.
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+beginfig(28);
+path p[];
+p1 = fullcircle scaled .6in;
+z1=(.75in,0)=-z3;
+z2=directionpoint left of p1=-z4;
+p2 = z1..z2..{curl1}z3..z4..{curl 1}cycle;
+fill p2 withcolor .4[white,black];
+unfill p1;
+draw p1;
+transform T;
+z1 transformed T = z2;
+z3 transformed T = z4;
+xxpart T=yypart T; yxpart T=-xypart T;
+picture pic;
+pic = currentpicture;
+for i=1 upto 2:
+ pic:=pic transformed T;
+ draw pic;
+endfor
+dotlabels.top(1,2,3); dotlabels.bot(4);
+endfig;
+\end{verbatim}
+\quad \mathcenter{\includegraphics{mpman-28.mps}}
+$$
+\caption{MetaPost code and the resulting ``fractal'' figure}
+\label{fig27}
+\end{figure}
+
+
+\subsection{Dashed Lines}
+
+The MetaPost language provides many ways of changing the appearance of a
+line besides just changing its width. One way is to use dashed lines as
+was done in Figures \ref{fig4} and~\ref{fig22}. The syntax for this
+is\index{dashed?\texttt{dashed}}\label{Ddashed}
+$$ {\tt draw}\, \descr{path expression}\, {\tt dashed}\, \descr{dash pattern} $$
+where a \tdescr{dash pattern}\index{dash pattern?\tdescr{dash pattern}}
+is really a special type of \tdescr{picture expression}. There is a
+predefined \tdescr{dash pattern} called {\tt
+evenly}\index{evenly?\texttt{evenly}}\label{Devenly} that makes dashes 3
+PostScript points long separated by gaps of the same size. Another
+predefined dash pattern {\tt
+withdots}\index{withdots?\texttt{withdots}}\label{Dwdots} produces
+dotted lines with dots 5 PostScript points apart.\footnote{{\tt
+withdots} is only found in MetaPost version 0.50 and higher.} For dots
+further apart or longer dashes further apart, the \tdescr{dash pattern}
+can be scaled\index{scaled?\texttt{scaled}} as shown in
+Figure~\ref{fig28}.
+
+\begin{figure}[htp]
+$$ \includegraphics{mpman-29.mps} $$
+\caption[Dashed lines and the corresponding dash patters]
+ {Dashed lines each labeled with the \tdescr{dash pattern} used to create
+ it.}
+\label{fig28}
+\end{figure}
+
+Another way to change a dash pattern is to alter its phase by shifting
+it horizontally. Shifting to the right makes the dashes move forward
+along the path and shifting to the left moves them backward.
+Figure~\ref{fig29} illustrates this effect. The dash pattern can be
+thought of as an infinitely repeating pattern strung out along a
+horizontal line where the portion of the line to the right of the
+$y$~axis is laid out along the path to be dashed\index{dash
+pattern?\tdescr{dash pattern}}.
+
+\begin{figure}[htp]
+$$ \includegraphics{mpman-30.mps} $$
+\caption[Dashed lines and the corresponding dash patters]
+ {Dashed lines and the MetaPost statements for drawing them where {\tt e4}
+ refers to the dash pattern {\tt evenly scaled 4}.}
+\label{fig29}
+\end{figure}
+
+When you shift a dash pattern so that the $y$~axis crosses the middle of
+a dash, the first dash gets truncated. Thus the line with dash pattern
+{\tt e4} starts with a dash of length 12bp followed by a 12bp gap and
+another 12bp dash, etc., while {\tt e4 shifted (-6bp,0)} produces a 6bp
+dash, a 12 bp gap, then a 12bp dash, etc. This dash pattern could be
+specified more directly via the {\tt dashpattern}\index{dash
+pattern?\texttt{dash pattern}}\label{Ddshpat} function:
+$$ \hbox{\tt dashpattern(on 6bp off 12bp on 6bp)} $$
+This means ``draw the first 6bp of the line, then skip the next 12bp, then draw
+another 6bp and repeat.'' If the line to be dashed is more than 30bp long, the
+last 6bp of the first copy of the dash pattern will merge with the first 6bp of
+the next copy to form a dash 12bp long. The general syntax for the
+{\tt dashpattern} function is shown in Figure~\ref{sydash}.
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{dash pattern} \rightarrow dashpattern
+ \hbox{\tt (}\descr{on/off list}\hbox{\tt )}$\\
+$\tt \descr{on/off list} \rightarrow
+ \descr{on/off list}\descr{on/off clause} \;|\; \descr{on/off clause}$\\
+$\tt \descr{on/off clause} \rightarrow on \descr{numeric tertiary}
+ \;|\; off \descr{numeric tertiary}$
+\end{ctabbing}
+\caption{The syntax for the {\tt dashpattern} function}
+\label{sydash}
+\end{figure}
+
+Since a dash pattern is really just a special kind of picture, the {\tt
+dashpattern} function returns a picture. It is not really necessary to
+know the structure of such a picture, so the casual reader will probably
+want to skip on to Section~\ref{oopt}. For those who want to know, a
+little experimentation shows that if {\tt d} is
+$$ \hbox{\tt dashpattern(on 6bp off 12bp on 6bp)}, $$
+then {\tt llcorner d} is $(0,24)$ and {\tt urcorner d} is $(24,24)$.
+Drawing {\tt d} directly without using it as a dash pattern produces two
+thin horizontal line segments like this:
+$$ \includegraphics{mpman-31.mps} $$
+The lines in this example are specified as having width zero, but this
+does not matter because the line width is ignored when a picture is used
+as a dash pattern.
+
+The general rule for interpreting a picture {\tt d} as a dash pattern is
+that the line segments in {\tt d} are projected onto the $x$-axis and
+the resulting pattern is replicated to infinity in both directions by
+placing copies of the pattern end-to-end. The actual dash lengths are
+obtained by starting at $x=0$ and scanning in the positive $x$
+direction.
+
+To make the idea of ``replicating to infinity'' more precise, let $P({\tt d})$
+be the projection of {\tt d} onto the $x$~axis, and let
+${\rm shift}(P({\tt d}),x)$ be the result of shifting {\tt d} by~$x$.
+The pattern resulting from infinite replication is
+$$ \bigcup_{{\rm integers}\ n} {\rm shift}(P(d),\, n\cdot\ell(d)), $$
+where $\ell(d)$ measures the length of $P(d)$. The most restrictive possible
+definition of this length is $d_{\rm max}-d_{\rm min}$,
+where $[d_{\rm min},d_{\rm max}]$
+is the range of $x$~coordinates in $P(d)$. In fact, MetaPost uses
+$$ \max(\left|y_0({\tt d})\right|,\, d_{\rm max}-d_{\rm min}), $$
+where $y_0({\tt d})$ is the $y$ coordinate of the contents of {\tt d}.
+The contents of {\tt d} should lie on a horizontal line, but if they do
+not, the MetaPost interpreter just picks a $y$~coordinate that occurs in
+{\tt d}\index{dash pattern?\tdescr{dash pattern}}.
+
+A picture used as a dashed pattern must contain no text or filled
+regions, but it can contain lines that are themselves dashed. This can
+give small dashes inside of larger dashes as shown in
+Figure~\ref{fig32}.\index{dash pattern?\tdescr{dash pattern}!recursive}
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+beginfig(32);
+draw dashpattern(on 15bp off 15bp) dashed evenly;
+picture p;
+p=currentpicture;
+currentpicture:=nullpicture;
+draw fullcircle scaled 1cm xscaled 3 dashed p;
+endfig;
+\end{verbatim}
+\quad \mathcenter{\includegraphics{mpman-32.mps}}
+$$
+\caption{MetaPost code for dashed patterns and the corresponding output}
+\label{fig32}
+\end{figure}
+
+\label{dashed-pens}
+Also, dashed patterns are intended to be used either with {\tt
+pencircle} or no pen at all; {\tt pensquare} and other complex pens
+should be avoided. This is because the output uses the PostScript
+primitive {\tt setdash}, which does not interact well with the filled
+paths created by polygonal pens. See Section~\ref{sec.pens}, p.\
+\pageref{sec.pens}.
+
+%\newpage
+
+\subsection{Local specials}
+
+If you want to attach a special bit of PostScript code, you can use
+$$
+{\tt withprescript} \descr{string expression}%
+\index{withprescript?\texttt{withprescript}}\label{Dwithpre}
+$$
+and
+$$
+{\tt withpostscript} \descr{string expression}%
+\index{withpostscript?\texttt{withpostscript}}\label{Dwithpost}
+$$
+The strings will be written to the output file before and after the
+current object, each beginning on their own line. You can specify
+multiple {\tt withprescript} or {\tt withpostscript} options if you
+like.
+
+When you specify more than one {\tt withprescript} or more than one {\tt
+ withpostscript} option, be wary of the fact that the scripts use a
+form of nesting: the {\tt withprescript} items are written to the
+PostScript file in last in, first out order; whereas the {\tt
+ withpostscript} items are written in first in, first out order.
+
+\subsection{Other Options}
+\label{oopt}
+
+You might have noticed that the dashed lines produced by {\tt dashed
+evenly}\index{evenly?\texttt{evenly}} appear to have more black than
+white. This is an effect of the {\tt
+linecap}\index{linecap?\texttt{linecap}}\label{Dlinecap} parameter that
+controls the appearance of the ends of lines as well as the ends of
+dashes. There are also a number of other ways to affect the appearance
+of things drawn with MetaPost.
+
+The {\tt linecap} parameter has three different settings just as in
+PostScript. Plain MetaPost gives this internal variable\index{internal
+variables}\index{variables!internal} the default value {\tt
+rounded}\index{rounded?\texttt{rounded}} which causes line segments to
+be drawn with rounded ends like the segment from {\tt z0} to {\tt z3} in
+Figure~\ref{fig33}. Setting ${\tt linecap}\mathrel{\hbox{\tt:=}}{\tt
+butt}$\index{butt?\texttt{butt}}\label{Dbutt} cuts the ends off flush so
+that dashes produced by {\tt dashed
+evenly}\index{evenly?\texttt{evenly}} have length 3bp, not 3bp plus the
+line width. You can also get squared-off ends that extend past the
+specified endpoints by setting ${\tt linecap}\mathrel{\hbox{\tt:=}}{\tt
+squared}$\index{squared?\texttt{squared}}\label{Dsqred} as was done in
+the line from {\tt z2} to {\tt z5} in Figure~\ref{fig33}.
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+beginfig(33);
+for i=0 upto 2:
+ z[i]=(0,40i); z[i+3]-z[i]=(100,30);
+endfor
+pickup pencircle scaled 18;
+draw z0..z3 withcolor .8white;
+linecap:=butt;
+draw z1..z4 withcolor .8white;
+linecap:=squared;
+draw z2..z5 withcolor .8white;
+dotlabels.top(0,1,2,3,4,5);
+endfig; linecap:=rounded;
+\end{verbatim}
+\qquad
+\mathcenter{\includegraphics{mpman-33.mps}}
+$$
+\caption{MetaPost code and the corresponding output}
+\label{fig33}
+\end{figure}
+
+Another parameter borrowed from PostScript affects the way a {\tt draw}
+statement treats sharp corners\index{corners} in the path to be drawn.
+The {\tt linejoin}\index{linejoin?\texttt{linejoin}}\label{Dlinejoin}
+parameter can be {\tt
+rounded}\index{rounded?\texttt{rounded}}\label{Drnded}, {\tt
+beveled}\index{beveled?\texttt{beveled}}\label{Dbvled}, or {\tt
+mitered}\index{mitered?\texttt{mitered}}\label{Dmitred} as shown in
+Figure~\ref{fig34}. The default value for plain MetaPost is {\tt
+rounded} which gives the effect of drawing with a circular brush.
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+beginfig(34);
+for i=0 upto 2:
+ z[i]=(0,50i); z[i+3]-z[i]=(60,40);
+ z[i+6]-z[i]=(120,0);
+endfor
+pickup pencircle scaled 24;
+draw z0--z3--z6 withcolor .8white;
+linejoin:=mitered;
+draw z1..z4--z7 withcolor .8white;
+linejoin:=beveled;
+draw z2..z5--z8 withcolor .8white;
+dotlabels.bot(0,1,2,3,4,5,6,7,8);
+endfig; linejoin:=rounded;
+\end{verbatim}
+\qquad
+\mathcenter{\includegraphics{mpman-34.mps}}
+$$
+\caption{MetaPost code and the corresponding output}
+\label{fig34}
+\end{figure}
+
+When {\tt linejoin} is {\tt mitered}, sharp corners generate long
+pointed features as shown in Figure~\ref{fig35}. Since this might be
+undesirable, there is an internal variable\index{internal
+variables}\index{variables!internal} called {\tt
+miterlimit}\index{miterlimit?\texttt{miterlimit}}\label{Dmiterlim} that
+controls how extreme the situation can get before the mitered join is
+replaced by a beveled join. For Plain MetaPost, {\tt miterlimit} has a
+default value of 10.0 and line joins revert to beveled when the ratio of
+miter length to line width reaches this value.
+
+\begin{figure}[htp]
+$$ \includegraphics{mpman-35.mps} $$
+\caption{The miter length and line width whose ratio is limited by
+ {\tt miterlimit}.}
+\label{fig35}
+\end{figure}
+
+The {\tt linecap}, {\tt linejoin}, and {\tt miterlimit} parameters are
+especially important because they also affect things that get drawn
+behind the scenes. For instance, Plain MetaPost has statements for
+drawing arrows\index{arrows}, and the arrowheads are slightly rounded
+when {\tt linejoin} is {\tt rounded}. The effect depends on the line
+width and is quite subtle at the default line width of 0.5bp as shown in
+Figure~\ref{fig36}.
+
+\begin{figure}[htp]
+$$\includegraphics{mpman-36.mps}$$
+\caption{Three ways of drawing arrows.}
+\label{fig36}
+\end{figure}
+
+Drawing arrows like the ones in Figure~\ref{fig36} is simply a matter of
+saying\index{drawarrow?\texttt{drawarrow}}\label{Ddrwarr}
+$$ {\tt drawarrow}\, \descr{path expression} $$
+instead of {\tt draw} \tdescr{path expression}. This draws the given
+path with an arrowhead at the last point on the path. If you want the
+arrowhead at the beginning of the path, just use the unary operator {\tt
+reverse}\index{reverse?\texttt{reverse}}\label{Drevrse} to take the
+original path and make a new one with its time sense reversed; i.e., for
+a path~{\tt p} with {\tt length p}${}=n$,
+$$ {\tt point\ } t {\tt\ of\ reverse\ p}
+ \quad {\rm and} \quad
+ {\tt point\ } n-t {\tt\ of\ p}
+$$ are synonymous.
+
+As shown in Figure~\ref{fig36}, a statement
+beginning\index{drawdblarrow?\texttt{drawdblarrow}}%
+\index{arrows!double-headed}\label{Ddrwdar}
+$$ {\tt drawdblarrow}\, \descr{path expression} $$
+draws a double-headed arrow. The size of the arrowhead is guaranteed to
+be larger than the line width, but it might need adjusting if the line
+width is very great. This is done by assigning a new value to the
+internal variable\index{internal variables}\index{variables!internal}
+{\tt ahlength}\index{ahlength?\texttt{ahlength}}\label{Dahlength} that
+determines arrowhead length as shown in Figure~\ref{fig37}. Increasing
+{\tt ahlength} from the default value of 4 PostScript points to 1.5
+centimeters produces the large arrowhead in Figure~\ref{fig37}. There
+is also an {\tt ahangle}\index{ahangle?\texttt{ahangle}}\label{Dahangle}
+parameter that controls the angle at the tip of the arrowhead. The
+default value of this angle is 45 degrees as shown in the figure.
+
+\begin{figure}[htp]
+$$ \includegraphics{mpman-37.mps} $$
+\caption[A large arrowhead with key parameters labeled.]
+ {A large arrowhead with key parameters labeled and paths used to
+ draw it marked with white lines.}
+\label{fig37}
+\end{figure}
+
+The arrowhead is created by filling the triangular region that is
+outlined in white in Figure~\ref{fig37} and then drawing around it with
+the currently picked up pen. This combination of filling and drawing
+can be combined into a single {\tt filldraw}
+statement\index{filldraw?\texttt{filldraw}}\label{Dfildrw}:
+$$ {\tt filldraw}\, \descr{path expression}\,
+ \descr{optional {\tt dashed} and {\tt withcolor} and {\tt withpen} clauses};
+$$
+The \tdescr{path expression} should be a closed cycle like the
+triangular path in Figure~\ref{fig37}. This path should not be confused
+with the path argument to {\tt drawarrow} which is indicated by a white
+line in the figure.
+
+White lines like the ones in the figure can be created by an {\tt
+undraw}\index{undraw?\texttt{undraw}}\label{Dundraw} statement. This is
+an erasing\index{erasing} version of {\tt draw} that draws {\tt
+withcolor background}\index{background?\texttt{background}} just as the
+{\tt unfill} statement does. There is also an {\tt
+unfilldraw}\index{unfilldraw?\texttt{unfilldraw}}\label{Dunfdrw}
+statement just in case someone finds a use for it.
+
+The {\tt filldraw}, {\tt undraw} and {\tt unfilldraw} statements and all
+the arrow drawing statements are like the {\tt fill} and {\tt draw}
+statements in that they take {\tt dashed}\index{dashed?\texttt{dashed}},
+{\tt withpen}\index{withpen?\texttt{withpen}}, and {\tt
+withcolor}\index{withcolor?\texttt{withcolor}} options. When you have a
+lot of drawing statements it is nice to be able to apply an option such
+as {\tt withcolor 0.8white} to all of them without having to type this
+repeatedly as was done in Figures \ref{fig33} and~\ref{fig34}. The
+statement for this purpose
+is\index{drawoptions?\texttt{drawoptions}}\label{Ddropts}
+$$ \hbox{\tt drawoptions(} \descr{text} \hbox{\tt )} $$
+where the \tdescr{text} argument gives a sequence of {\tt dashed}, {\tt
+withcolor}, and {\tt withpen} options to be applied automatically to all
+drawing statements. If you specify
+$$ \hbox{\tt drawoptions(withcolor .5[black,white])} $$
+and then want to draw a black line, you can override the {\tt drawoptions}
+by specifying
+$$ {\tt draw}\, \descr{path expression}\, {\tt withcolor\ black} $$
+To turn off {\tt drawoptions} all together, just give an empty list:
+$$ \hbox{\tt drawoptions()} $$
+(This is done automatically by the {\tt
+beginfig}\index{beginfig?\texttt{beginfig}} macro).
+
+Since irrelevant options are ignored, there is no harm in giving a statement
+like
+$$ \hbox{\tt drawoptions(dashed evenly)} $$
+followed by a sequence of {\tt draw} and {\tt fill} commands. It does
+not make sense to use a dash pattern when filling so the {\tt dashed
+evenly} gets ignored for {\tt fill} statements. It turns out that
+$$ \hbox{\tt drawoptions(withpen } \descr{pen expression} \hbox{\tt )} $$
+does affect {\tt fill} statements as well as {\tt draw} statements.
+In fact there is a special pen variable called
+{\tt currentpen}\index{currentpen?\texttt{currentpen}} such that
+{\tt fill} \ldots\ {\tt withpen currentpen} is equivalent to a {\tt filldraw}
+statement.
+
+Precisely what does it mean to say that drawing options affect those
+statements where they make sense? The {\tt dashed} \tdescr{dash
+pattern} option only affects
+$$ {\tt draw}\, \descr{path expression} $$
+statements, and text appearing in the \tdescr{picture expression} argument to
+$$ {\tt draw}\, \descr{picture expression} $$
+statement is only affected by the {\tt withcolor} \tdescr{color
+expression} option. For all other combinations of drawing statements
+and options, there is some effect. An option applied to a {\tt draw}
+\tdescr{picture expression} statement will in general affect some parts
+of the picture but not others. For instance, a {\tt dashed} or {\tt
+withpen} option will affect all the lines in the picture but none of the
+labels.
+
+
+\subsection{Pens}
+\label{sec.pens}
+
+Previous sections have given numerous examples of {\tt pickup}
+\tdescr{pen expression} and {\tt withpen} \tdescr{pen expression}, but
+there have not been any examples of pen expressions other than
+$$ {\tt pencircle\ scaled}\, \descr{numeric primary} $$
+which produces lines of a specified width. For calligraphic effects
+such in Figure~\ref{fig38}, you can apply any of the transformation
+operators discussed in Section~\ref{transsec}. The starting point for
+such transformations is {\tt
+pencircle}\index{pencircle?\texttt{pencircle}}\label{Dpncirc}, a circle
+one PostScript point in diameter. Thus affine transformations produce a
+circular or elliptical\index{pens!elliptical} pen shape. The width of
+lines drawn with the pen depends on how nearly perpendicular the line is
+to the long axis of the ellipse.
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+beginfig(38);
+pickup pencircle scaled .2in yscaled .08 rotated 30;
+x0=x3=x4;
+z1-z0 = .45in*dir 30;
+z2-z3 = whatever*(z1-z0);
+z6-z5 = whatever*(z1-z0);
+z1-z6 = 1.2*(z3-z0);
+rt x3 = lft x2;
+x5 = .55[x4,x6];
+y4 = y6;
+lft x3 = bot y5 = 0;
+top y2 = .9in;
+draw z0--z1--z2--z3--z4--z5--z6 withcolor .7white;
+dotlabels.top(0,1,2,3,4,5,6);
+endfig;
+\end{verbatim}
+\quad \mathcenter{\includegraphics{mpman-38.mps}}
+$$
+\caption{MetaPost code and the resulting ``calligraphic'' figure.}
+\label{fig38}\index{lft?\texttt{lft}}\index{bot?\texttt{bot}}\index{top?\texttt{top}}
+\end{figure}
+
+Figure~\ref{fig38} demonstrates operators {\tt
+lft}\index{lft?\texttt{lft}}\label{Dlft}, {\tt
+rt}\index{rt?\texttt{rt}}\label{Drt}, {\tt
+top}\index{top?\texttt{top}}\label{Dtop}, and {\tt
+bot}\index{bot?\texttt{bot}}\label{Dbot} that answer the question, ``If
+the current pen is placed at the position given by the argument, where
+will its left, right, top, or bottom edge be?'' In this case the
+current pen is the ellipse given in the {\tt pickup} statement and its
+bounding box is 0.1734 inches wide and 0.1010 inches high, so {\tt rt
+x3} is ${\tt x3}+{\tt 0.0867in}$ and {\tt bot y5} is ${\tt y5}-{\tt
+0.0505in}$. The {\tt lft}, {\tt rt}, {\tt top}, and {\tt bot} operators
+also accept arguments of type pair in which case they compute the $x$
+and~$y$ coordinates of the leftmost, rightmost, topmost, or bottommost
+point on the pen shape. For example,
+$$ {\tt rt}(x,y) = (x,y)+({\tt 0.0867in}, {\tt 0.0496in}) $$
+for the pen in Figure~\ref{fig38}. Note that {\tt
+beginfig}\index{beginfig?\texttt{beginfig}} resets the current pen to a
+default value of
+$$ \hbox{\tt pencircle scaled 0.5bp} $$
+at the beginning of each figure. This value can be reselected at any
+time by giving the command {\tt pickup
+defaultpen}\index{defaultpen?\texttt{defaultpen}}\label{Ddefaultpen}.
+
+This would be the end of the story on pens, except that for
+compatibility with \MF\index{metafont?\MF}, MetaPost also allows pen
+shapes to be polygonal\index{pens!polygonal}. There is a predefined pen
+called {\tt pensquare}\index{pensquare?\texttt{pensquare}}\label{Dpnsqr}
+that can be transformed to yield pens shaped like parallelograms.
+
+In fact, there is even an operator called {\tt
+makepen}\index{makepen?\texttt{makepen}}\label{Dmkpen} that takes a
+convex-polygon-shaped path and makes a pen that shape and size. If the
+path is not exactly convex or polygonal, the {\tt makepen} operator will
+straighten the edges and/or drop some of the vertices. In particular,
+{\tt pensquare} is equivalent to
+$$ \hbox{\verb|makepen((-.5,-.5)--(.5,-.5)--(.5,.5)--(-.5,.5)--cycle)|} $$
+
+{\tt pensquare} and {\tt makepen} should not be used with dash
+patterns. See the end of Section~\ref{dashed-pens}, p.\
+\pageref{dashed-pens}.
+
+The inverse of {\tt makepen} is the {\tt
+makepath}\index{makepath?\texttt{makepath}}\label{Dmkpath} operator that
+takes a \tdescr{pen primary} and returns the corresponding path. Thus
+{\tt makepath pencircle} produces a circular path identical to {\tt
+fullcircle}\index{fullcircle?\texttt{fullcircle}}. This also works for
+a polygonal pen so that
+$$ {\tt makepath\ makepen}\, \descr{path expression} $$
+will take any cyclic path and turn it into a convex polygon\index{convex polygons}.
+
+
+\subsection{Clipping and Low-Level Drawing Commands}
+
+Drawing statements such as {\tt draw}, {\tt fill}, {\tt filldraw}, and
+{\tt unfill} are part of the Plain macro\index{Plain macros} package and
+are defined in terms of more primitive statements. The main difference
+between the drawing statements discussed in previous sections and the
+more primitive versions is that the primitive drawing statements all
+require you to specify a picture variable to hold the results. For {\tt
+fill}, {\tt draw}, and related statements, the results always go to a
+picture variable called {\tt
+currentpicture}\index{currentpicture?\texttt{currentpicture}}\label{Dcurpic}.
+The syntax for the primitive drawing statements that allow you to
+specify a picture variable is shown in Figure~\ref{sydraw}.
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{addto command} \rightarrow$\\
+$\tt \qquad addto \descr{picture variable} also
+ \descr{picture expression} \descr{option list}$\\
+$\tt \qquad \;|\; addto \descr{picture variable}
+ contour \descr{path expression} \descr{option list}$\\
+$\tt \qquad \;|\; addto \descr{picture variable}
+ doublepath \descr{path expression} \descr{option list}$\\
+$\tt \descr{option list} \rightarrow \descr{empty} \;|\;
+ \descr{drawing option} \descr{option list}$\\
+$\tt \descr{drawing option} \rightarrow withcolor \descr{color expression}$\\
+$\tt \qquad \;|\; withrgbcolor \descr{rgbcolor expression} \;|\;
+ withcmykcolor \descr{cmykcolor expression}$\\
+$\tt \qquad \;|\; withgreyscale \descr{numeric expression} \;|\;
+ withoutcolor$\\
+$\tt \qquad \;|\; withprescript \descr{string expression} \;|\;
+ withpostscript \descr{string expression}$\\
+$\tt \qquad \;|\; withpen \descr{pen expression} \;|\;
+ dashed \descr{picture expression}$
+\end{ctabbing}
+\caption{The syntax for primitive drawing statements}
+\label{sydraw}
+\index{option list?\tdescr{option list}}\index{addto also?\texttt{addto also}}\index{addto contour?\texttt{addto contour}}%
+\index{addto doublepath?\texttt{addto doublepath}}\index{withcolor?\texttt{withcolor}}\index{withpen?\texttt{withpen}}%
+\index{dashed?\texttt{dashed}}\index{drawing option?\tdescr{drawing option}}
+\end{figure}
+
+The syntax for primitive drawing commands is compatible with
+\MF\index{metafont?\MF}. Table~\ref{draweqv} shows how the primitive
+drawing statements relate to the familiar {\tt draw} and {\tt fill}
+statements. Each of the statements in the first column of the table
+could be ended with an \tdescr{option list} of its own, which is
+equivalent to appending the \tdescr{option list} to the corresponding
+entry in the second column of the table. For example,
+$$ {\tt draw}\ p\ {\tt withpen\ pencircle} $$
+is equivalent to
+$$ {\tt addto\ currentpicture\ doublepath}\ p\
+ {\tt withpen\ currentpen\ withpen\ pencircle}
+$$
+where {\tt
+currentpen}\index{currentpen?\texttt{currentpen}}\label{Dcurpen} is a
+special pen variable that always holds the last pen picked up. The
+second {\tt withpen} option silently overrides the {\tt withpen
+currentpen} from the expansion of {\tt draw}.
+
+\begin{table}[htp]
+$$\begin{tabular}{|l|l|} \hline
+\multicolumn1{|c|}{statement}& \multicolumn1{c|}{equivalent primitives}\\ \hline
+{\tt draw} {\it pic}& {\tt addto currentpicture also} {\it pic}\\
+{\tt draw} $p$& {\tt addto currentpicture doublepath} $p$
+ {\tt withpen} $q$\\
+{\tt fill} $c$& {\tt addto currentpicture contour} $c$\\
+{\tt filldraw} $c$& {\tt addto currentpicture contour} $c$ {\tt withpen} $q$\\
+{\tt undraw} {\it pic}& {\tt addto currentpicture also} {\it pic}
+ {\tt withcolor} $b$\\
+{\tt undraw} $p$& {\tt addto currentpicture doublepath} $p$
+ {\tt withpen} $q$
+ {\tt withcolor} $b$\\
+{\tt unfill} $c$& {\tt addto currentpicture contour} $c$
+ {\tt withcolor} $b$\\
+{\tt unfilldraw} $c$& {\tt addto currentpicture contour} $c$ {\tt withpen} $q$
+ {\tt withcolor} $b$\\ \hline
+\end{tabular}
+$$
+\caption[Drawing statements and equivalent primitive commands] {Common
+ drawing statements and equivalent primitive versions, where $q$
+ stands for {\tt currentpen}, $b$ stands for {\tt background},
+ $p$ stands for any path, $c$ stands for a cyclic path, and {\it
+ pic} stands for a \tdescr{picture expression}. Note that
+ nonempty {\tt drawoptions} would complicate the entries in the
+ second column.}
+\label{draweqv}
+\index{drawoptions?\texttt{drawoptions}}
+\end{table}
+
+
+There are two more primitive drawing commands that do not accept any
+drawing options. One is the {\tt setbounds} command that was discussed
+in Section~\ref{meas}; the other is the {\tt clip}
+command\index{clip?\texttt{clip}}\label{Dclip}:
+$$ {\tt clip}\, \descr{picture variable}\, {\tt to}\, \descr{path expression} $$
+Given a cyclic path, this statement trims the contents of the
+\tdescr{picture variable} to eliminate everything outside of the cyclic path.
+There is no ``high level'' version of this statement, so you have to use
+$$ {\tt clip\ currentpicture\ to}\, \descr{path expression} $$
+if you want to clip {\tt
+currentpicture}\index{currentpicture?\texttt{currentpicture}}.
+Figure~\ref{fig40} illustrates clipping.
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+beginfig(40);
+path p[];
+p1 = (0,0){curl 0}..(5pt,-3pt)..{curl 0}(10pt,0);
+p2 = p1..(p1 yscaled-1 shifted(10pt,0));
+p0 = p2;
+for i=1 upto 3: p0:=p0.. p2 shifted (i*20pt,0);
+ endfor
+for j=0 upto 8: draw p0 shifted (0,j*10pt);
+ endfor
+p3 = fullcircle shifted (.5,.5) scaled 72pt;
+clip currentpicture to p3;
+draw p3;
+endfig;
+\end{verbatim}
+\qquad
+\mathcenter{\includegraphics{mpman-40.mps}}
+$$
+\caption{MetaPost code and the resulting ``clipped'' figure.}
+\label{fig40}
+\end{figure}
+
+All the primitive drawing operations would be useless without one last
+operation called {\tt shipout}. The
+statement\index{shipout?\texttt{shipout}}\label{Dship}
+$$ {\tt shipout}\, \descr{picture expression} $$
+writes out a picture as a PostScript\index{PostScript} file whose
+file name is determined by
+{\tt outputtemplate}\index{outputtemplate?\texttt{outputtemplate}}
+(see Section~\ref{Doutputtemplate}). By default, the file name ends
+{\tt.}{\it nnn}, where {\tt nnn} is the decimal representation
+of the value of the internal variable\index{internal
+variables}\index{variables!internal} {\tt
+charcode}\index{charcode?\texttt{charcode}}\label{Dcharcode}. (The name
+``{\tt charcode}'' is for compatibility with \MF\index{metafont?\MF}.)
+Normally, {\tt beginfig}\index{beginfig?\texttt{beginfig}} sets {\tt
+charcode}, and {\tt endfig}\index{endfig?\texttt{endfig}} invokes {\tt
+shipout}.
+
+\subsection{Directing Output to a Picture Variable}
+Sometimes, it might be desirable to save the output of a drawing
+operation and re-use them later. This can easily be done with
+MetaPost primitives like \ttt{addto}. On the other hand, since the
+higher-level drawing commands defined in the Plain macro package
+always write to the
+\ttt{currentpicture}\index{currentpicture?\texttt{currentpicture}},
+saving their output required to temporarily save \ttt{currentpicture},
+reset it to \ttt{nullpicture}\index{nullpicture?\texttt{nullpicture}},
+execute the drawing operations, save the \ttt{currentpicture} to a
+new \ttt{picture} variable and finally restore \ttt{currentpicture} to
+the saved state. In MetaPost version~0.60 a new macro
+$$ \hbox{\tt image( $\descr{drawing commands}$ )} $$%
+\index{image?\texttt{image}}\label{Dimage}%
+was introduced that eases this task. It takes as input a sequence of arbitrary
+drawing operations and returns a \ttt{picture} variable containing the
+corresponding output, without affecting {\tt currentpicture}.
+
+As an example, in the code of figure~\ref{fig55} an object \ttt{wheel} has
+been defined that saves the output of two \ttt{draw} operations as follows:
+\begin{figure}[b]
+$$ \includegraphics{mpman-55.mps} $$
+\caption{Copying objects with the \ttt{image} operator.}
+\label{fig55}
+\end{figure}
+$$\begin{verbatim}
+picture wheel;
+wheel := image(
+ draw fullcircle scaled 2u xscaled .8 rotated 30;
+ draw fullcircle scaled .15u xscaled .8 rotated 30;
+);
+\end{verbatim}
+$$
+This \ttt{wheel} object is re-used in the definition of another object \ttt{car}.
+Figure~\ref{fig55} shows three \ttt{car} objects drawn with two different slant
+values.
+
+
+\subsection{Inspecting the Components of a Picture}
+\label{piccomp}
+
+\mbox{}% Start paragraph here.
+\index{setbounds?\texttt{setbounds}|(}%
+\index{for within?\texttt{for within}|(}%
+%
+MetaPost pictures are composed of stroked lines, filled outlines, pieces
+of typeset text, clipping paths\index{clip?\texttt{clip}}, and
+{\tt setbounds}\index{setbounds?\texttt{setbounds}} paths. (A {\tt setbounds}
+path gives an artificial bounding box as is needed for \TeX\ output.)
+A picture can have many components of each type. They can be accessed via
+an iteration of the form
+$$ {\tt for}\ \descr{symbolic token}\ {\tt within}\
+ \descr{picture expression}\hbox{\tt:}\ \descr{loop text}\ {\tt endfor}
+$$\index{for within?\texttt{for within}}\label{Dforwithin}%
+The \tdescr{loop text} can be anything that is balanced with respect to
+{\tt for} and {\tt endfor}. The \tdescr{symbolic token} is a loop variable that
+scans the components of the picture in the order in which they were drawn. The
+component for a clipping or {\tt setbounds} path includes everything the path
+applies to. Thus if a single clipping or {\tt setbounds} path applies to
+everything in the \tdescr{picture expression}, the whole picture could be
+thought of as one big component. In order to make the contents of such a picture
+accessible, the {\tt for}\ldots{\tt within} iteration ignores the enclosing
+clipping or {\tt setbounds} path in this case. The number of components
+that a {\tt for}\ldots {\tt within} iteration would find is returned by
+$$ {\tt length}\ \descr{picture primary}\index{length?\texttt{length}}\label{DlengthPicture}$$
+
+\index{for within?\texttt{for within}|)}
+
+\mbox{}% Start paragraph here.
+\index{stroked?\texttt{stroked}|(}%
+\index{filled?\texttt{filled}|(}%
+\index{textual?\texttt{textual}|(}%
+\index{clipped?\texttt{clipped}|(}%
+\index{bounded?\texttt{bounded}|(}%
+%
+Once the {\tt for}\ldots{\tt within} iteration has found a picture component,
+there are numerous operators for identifying it and extracting relevant
+information. The operator
+$$ {\tt stroked}\ \descr{primary expression} $$\index{stroked?\texttt{stroked}}\label{Dstroked}%
+tests whether the expression is a known picture whose first component is a
+stroked line. Similarly, the {\tt filled}\index{filled?\texttt{filled}}\label{Dfilled}
+and {\tt textual}\index{textual?\texttt{textual}}\label{Dtextual} operators
+return {\tt true} if the first component is a filled outline or a piece of
+typeset text. The {\tt clipped}\index{clipped?\texttt{clipped}}\label{Dclipped}
+and {\tt bounded}\index{bounded?\texttt{bounded}}\label{Dbounded} operators
+test whether the argument is a known picture that starts with a clipping
+path or a {\tt setbounds} path. This is true if the first component is
+clipped or bounded or if the entire picture is enclosed in a clipping or
+{\tt setbounds} path.
+
+\mbox{}% Start paragraph here.
+\index{pathpart?\texttt{pathpart}|(}%
+\index{penpart?\texttt{penpart}|(}%
+\index{dashpart?\texttt{dashpart}|(}%
+%
+There are also numerous part extraction operators that test the first component
+of a picture. If {\tt p} is a picture and {\tt stroked p} is true,
+{\tt pathpart p}\index{pathpart?\texttt{pathpart}}\label{Dpathpart} is the
+path describing the line that got stroked,
+{\tt penpart p}\index{penpart?\texttt{penpart}}\label{Dpenpart} is the pen
+that was used, {\tt dashpart p}\index{dashpart?\texttt{dashpart}}\label{Ddashpart}
+is the dash pattern. If the line is not dashed, {\tt dashpart p}
+returns an empty picture.
+
+The same part extraction operators work when {\tt filled p} is true, except
+that {\tt dashpart p} is not meaningful in that case.
+
+For text components, {\tt textual p} is true,
+{\tt textpart p}\index{textpart?\texttt{textpart}}\label{Dtextpart}
+gives the text that got typeset,
+{\tt fontpart p}\index{fontpart?\texttt{fontpart}}\label{Dfontpart}
+gives the font that was used, and {\tt xpart~p}\index{xpart?\texttt{xpart}}\index{ypart?\texttt{ypart}}\index{xxpart?\texttt{xxpart}}%
+\index{xypart?\texttt{xypart}}\index{yxpart?\texttt{yxpart}}\index{yypart?\texttt{yypart}},
+{\tt ypart~p}, {\tt xxpart~p}, {\tt xypart~p}, {\tt yxpart~p}, {\tt yypart~p}
+tell how the text has been shifted, rotated, and scaled.
+
+\mbox{}% Start paragraph here.
+\index{colorpart?\texttt{colorpart}|(}%
+\index{colormodel?\texttt{colormodel}|(}%
+\index{redpart?\texttt{redpart}|(}%
+\index{greenpart?\texttt{greenpart}|(}%
+\index{bluepart?\texttt{bluepart}|(}%
+\index{cyanpart?\texttt{cyanpart}|(}%
+\index{magentapart?\texttt{magentapart}|(}%
+\index{yellowpart?\texttt{yellowpart}|(}%
+\index{blackpart?\texttt{blackpart}|(}%
+\index{greypart?\texttt{greypart}|(}%
+%
+Finally, for \ttt{stroked}, \ttt{filled} and \ttt{textual} components
+the color can be examined by saying
+$$ {\tt colorpart}\
+\descr{item}\index{colorpart?\texttt{colorpart}}\label{Dcolorpart}
+$$
+This returns the color of a component in its respective color model.
+The color model of a component can be identified by the
+\ttt{colormodel}\index{colormodel?\texttt{colormodel}}\label{Dcolormodel}
+operator (cf. Table~\ref{dfltcmod} on p.~\pageref{dfltcmod}).
+
+For more fine grained color operations there are operators to extract
+single color components of an item. Depending on the color model the
+color of a picture component \ttt{p} is
+$$ \hbox{\tt (cyanpart p, magentapart p, yellowpart p, blackpart p)} $$%
+\index{cyanpart?\texttt{cyanpart}}\index{magentapart?\texttt{magentapart}}\index{yellowpart?\texttt{yellowpart}}\index{blackpart?\texttt{blackpart}}
+or
+$$ \hbox{\tt (redpart p, greenpart p, bluepart p)} $$%
+\index{redpart?\texttt{redpart}}\index{greenpart?\texttt{greenpart}}\index{bluepart?\texttt{bluepart}}
+or
+$$ \hbox{\tt greypart p} $$%
+\index{greypart?\texttt{greypart}}
+or
+$$ \hbox{\tt false}. $$
+
+Note, color part operators {\tt redpart}, {\tt cyanpart} etc. have to
+match the color model of the picture component in question. Applying a
+non-matching color part operator to a picture component triggers an
+error and returns a \ttindex{black} color part in the requested color
+model. That is, for the code
+$$\begin{verbatim}
+picture pic;
+pic := image(fill unitsquare scaled 1cm withcolor (0.3, 0.6, 0.9););
+for item within pic:
+ show greypart item;
+ show cyanpart item;
+ show blackpart item;
+ show redpart item;
+endfor
+\end{verbatim}
+$$
+the output is (omitting the error messages)
+$$\begin{verbatim}
+>> 0
+>> 0
+>> 1
+>> 0.3
+\end{verbatim}
+$$
+since in grey scale color model black is {\tt 0} and in CMYK color model
+black is {\tt (0,0,0,1)}. For the matching RGB color model the true
+color component is returned.
+
+When {\tt clipped p} or {\tt bounded p} is true, {\tt pathpart p} gives the
+clipping or {\tt setbounds} path and the other part extraction operators are
+not meaningful. Such non-meaningful part extractions do not generate
+errors. Instead, they return null values or black color (components):
+the trivial path {\tt (0,0)} for {\tt pathpart},
+{\tt nullpen}\index{nullpen?\texttt{nullpen}}\label{Dnlpen} for {\tt penpart},
+an empty picture for {\tt dashpart},
+the null string for {\tt textpart} or {\tt fontpart},
+zero for {\tt colormodel},
+{\tt greypart},
+{\tt redpart}, {\tt greenpart}, {\tt bluepart},
+{\tt cyanpart}, {\tt magentapart}, {\tt yellowpart},
+one for {\tt blackpart}, and
+black in the current default color model for {\tt colorpart}.
+
+To summarize the discussion of mismatching part operators:
+\begin{enumerate}
+\item Asking for non-meaningful parts of an item---such as the {\tt
+ redpart} of a clipping path, the {\tt textpart} of a stroked item,
+ or the {\tt pathpart} of a textual item---is silently accepted and
+ returns a null value or a black color (component).
+\item Explicitly asking for a color part of a colored item in the wrong
+ color model returns a black color component. This operation triggers
+ an error.
+\end{enumerate}
+
+\index{setbounds?\texttt{setbounds}|)}
+\index{stroked?\texttt{stroked}|)}
+\index{filled?\texttt{filled}|)}
+\index{textual?\texttt{textual}|)}
+\index{clipped?\texttt{clipped}|)}
+\index{bounded?\texttt{bounded}|)}
+\index{pathpart?\texttt{pathpart}|)}
+\index{penpart?\texttt{penpart}|)}
+\index{dashpart?\texttt{dashpart}|)}
+\index{colormodel?\texttt{colormodel}|)}
+\index{colorpart?\texttt{colorpart}|)}
+\index{redpart?\texttt{redpart}|)}
+\index{greenpart?\texttt{greenpart}|)}
+\index{bluepart?\texttt{bluepart}|)}
+\index{cyanpart?\texttt{cyanpart}|)}
+\index{magentapart?\texttt{magentapart}|)}
+\index{yellowpart?\texttt{yellowpart}|)}
+\index{blackpart?\texttt{blackpart}|)}
+\index{greypart?\texttt{greypart}|)}
+
+
+\subsection{Decomposing the Glyphs of a Font}
+\label{glyphs}
+
+MetaPost provides a primitive to convert a
+glyph\index{glyph}\index{font!glyph} of a font in the Adobe Type~1
+Font\index{PostScript!fonts}\index{font!PostScript}\index{Adobe Type~1
+ Font}\index{font!Adobe Type~1} format into its constituent filled
+paths---the strokes---and store them in a picture variable. A glyph is
+the visual representation of a character in a font. A
+character\index{character}\index{font!character} is a certain
+slot\index{slot}\index{font!slot} (index) in a font with an associated
+meaning, e.g., the capital letter~``M'' or the exclamation mark. The
+meaning of a slot is defined by the font
+encoding\index{encoding}\index{font!encoding}. In general, the same
+character is represented by different glyphs in different fonts.
+Figure~\ref{glyphsample} shows some glyphs for the character at slot~103
+in the T1 encoding, i.e., the lower-case letter~``g''. All glyphs are
+at the same nominal size. Note, how glyphs may extend beyond their
+bounding box.
+\begin{figure}[htp]
+ \centering
+ \setlength{\fboxsep}{0pt}
+ \setlength{\fboxrule}{.125pt}
+ \fontsize{56pt}{56pt}\selectfont
+ \newcommand*{\showglyph}[4]{% a glyph with its bounding box
+ \fbox{\usefont{#1}{#2}{#3}{#4}g}%
+ }
+ \makebox[0pt][c]{% base line
+ \rule{.7\textwidth}{.125pt}%
+ }%
+ \makebox[0pt][c]{% glyphs
+ \showglyph{T1}{lmr}{m}{n}\hspace{.3em}
+ \showglyph{T1}{qag}{m}{n}\hspace{.3em}
+ \showglyph{T1}{qpl}{m}{it}\hspace{.3em}
+ \showglyph{T1}{qzc}{m}{it}%
+ }
+ \caption{Different glyphs representing the same character.}
+ \label{glyphsample}
+\end{figure}
+
+The glyphs of an Adobe Type~1
+font\index{PostScript!fonts}\index{font!PostScript}\index{Adobe Type~1
+ Font}\index{font!Adobe Type~1} are composed of two types of contours:
+Clockwise oriented contours add to the shape of a glyph and are filled
+with black ink. Counter-clockwise oriented contours
+erase\index{erasing} parts of other contours, i.e., make them
+transparent again. To save the contours of a glyph in a picture, the
+\verb|glyph|\index{glyph?\texttt{glyph}}\label{Dglyph} operator can be
+used. There are two ways to identify a glyph in a font:
+\begin{eqnarray*}
+ & \verb|glyph|\, \descr{numeric expression}\, \verb|of|\,
+ \descr{string expression}\\
+ \noalign{\hbox{and}}
+ & \verb|glyph|\, \descr{string expression}\, \verb|of|\,
+ \descr{string expression}\rlap{\quad\mbox{.}}
+\end{eqnarray*}
+
+If the first argument is a numeric expression, it has to be a slot
+number between 0 and~255. Fractional slot numbers are rounded to the
+nearest integer value. Slot numbers outside the allowed range trigger
+an error. If the first argument is string, it has to be a CharString
+name\index{CharString name} in the PostScript font's source file. A
+CharString name is a unique text label for a glyph in a PostScript font
+(a font encoding actually maps CharStrings to slots). This second
+syntax can be used to address glyphs without having to think about font
+encodings. The second argument to the \verb|glyph| operator is a string
+containing a font name (section~\ref{text} has more on font names).
+
+The \verb|glyph| operator looks-up the font name in the font map to
+determine the encoding and to find the font's PostScript source file.
+It returns a picture consisting of the glyph's contour lines, explicitly
+filled black and white in the greyscale color model according to the
+rules laid out above. Additionally, the contours are sorted, such that
+all black contours are drawn before white contours. The filling and
+sorting is necessary for the picture to resembles the corresponding
+glyph visually\footnote{Plain contours already carry enough information
+ to completely reconstruct a glyph, the orientation of a contour can be
+ computed from its cardinal and control points. MetaPost has a
+ \texttt{turningnumber}\index{turningnumber?\texttt{turningnumber}}\label{Dturningnumber}
+ primitive to do that.}, since Adobe Type~1
+fonts\index{PostScript!fonts}\index{font!PostScript}\index{Adobe Type~1
+ Font}\index{font!Adobe Type~1} use a generalized variant of the
+non-zero winding number fill rule\index{non-zero fill rule}\index{fill
+ rule!non-zero}\index{PostScript!fill rule}, which MetaPost doesn't
+implement (MetaPost cannot handle non-contiguous paths). As a side
+effect, the interiors of the erasing\index{erasing} contours are an
+opaque white in the returned picture, while they were transparent in the
+original glyph. One can think of erasing contours to be unfilled (see
+p.~\pageref{Dunfill}). For instance, the following code saves the
+contours of the lower case letter~``g'', bound to slot~103 in the OT1
+encoding\index{OT1 encoding}\index{encoding!OT1}, in the
+Computer\index{Computer Modern Roman} Modern Roman font in a picture
+variable:
+
+$$
+\begin{verbatim}
+fontmapline "cmr10 CMR10 <cmr10.pfb";
+picture g;
+g := glyph 103 of "cmr10";
+\end{verbatim}
+$$
+
+The \verb|glyph| operator returns an empty picture, if the
+\texttt{.tfm}\index{tfm file?{\tt tfm} file}\index{files!tfm?{\tt tfm}}
+or \texttt{.pfb}\index{pfb file?{\tt pfb} file}\index{files!pfb?{\tt
+ pfb}} file cannot be found, if the encoding given in the font map
+cannot be found or the slot number is not covered by the encoding or if
+the CharString name cannot be found. Note, while MetaPost delegates the
+actual font handling to a rendering application for \verb|infont| and
+\verb|btex| \ldots\ \verb|etex| blocks, the \verb|glyph| operator
+directly operates on font ressources. For that reason, a font map entry
+is mandatory for the font in question, given either by
+\verb|fontmapline| or \verb|fontmapfile| (see
+section~\ref{Dfontmapline}).
+
+In Figure~\ref{fig56}, the contours of the upper case letter~``\v{D}''
+in the Latin\index{Latin Modern Roman} Modern Roman font are saved in a
+picture variable. The glyph is identified by its CharString name
+``Dcaron''\index{Dcaron}. The code then iterates over all contours and
+draws them together with their cardinal (black) and control points
+(red). As it turns out, many of the control points coincide with
+cardinal points in this glyph.
+
+\begin{figure}[htb]
+$$
+\begin{verbatim}
+fontmapfile "=lm-ec.map";
+beginfig(56);
+ picture q;
+ path p;
+ interim ahlength := 12bp;
+ interim ahangle := 25;
+ q := glyph "Dcaron" of "ec-lmr10" scaled .2;
+ for item within q:
+ p := pathpart item;
+ drawarrow p withcolor (.6,.9,.6)
+ withpen pencircle scaled 1.5;
+ for j=0 upto length p:
+ pickup pencircle scaled .7;
+ draw (point j of p -- precontrol j of p)
+ dashed evenly withcolor blue;
+ draw (point j of p -- postcontrol j of p)
+ dashed evenly withcolor blue;
+ pickup pencircle scaled 3;
+ draw precontrol j of p withcolor red;
+ draw postcontrol j of p withcolor red;
+ pickup pencircle scaled 2;
+ draw point j of p withcolor black;
+ endfor
+ endfor
+endfig;
+\end{verbatim}
+\qquad
+\mathcenter{\includegraphics{mpman-56.mps}}
+$$
+\caption{Iterating over the contours of a glyph}
+\label{fig56}
+\end{figure}
+
+The contours in a picture returned by the \verb|glyph| operator are no
+raw copies of the contours found in the font sources, but the
+\verb|glyph| operator applies a number of transformations to them.
+First, the direction of all contours is reversed, so that contours
+filled black become counter-clockwise oriented (mathematically positive)
+and contours filled white become clockwise oriented (mathematically
+negative). Second, in an Adobe Type~1
+font\index{PostScript!fonts}\index{font!PostScript}\index{Adobe Type~1
+ Font}\index{font!Adobe Type~1}, contours are in general closed by
+repeating the starting point before applying the \verb|closepath|
+operator\index{PostScript!closepath operator?\texttt{closepath}
+ operator}. The MetaPost representation of such a path would be:
+$$
+z_0\verb|..|\mbox{\itshape controls}\verb|..|z_1\verb|..| \cdots
+\verb|..|z_n\verb|..|\mbox{\itshape controls}\verb|..|z_0\verb|--cycle|
+$$
+However, a more natural MetaPost representation of that path would be:
+$$
+z_0\verb|..|\mbox{\itshape controls}\verb|..|z_1\verb|..| \cdots
+\verb|..|z_n\verb|..|\mbox{\itshape controls}\verb|..cycle|
+$$
+The \verb|glyph| operator transforms all paths into the latter
+representation, i.e., the last point is removed, whenever it matches the
+starting point. Finally, the picture returned by the \verb|glyph|
+operator is scaled, such that one font design unit\index{font!design
+ unit} equals one PostScript
+point\index{point!PostScript}\index{PostScript!point} (bp). A usual
+font design unit is a thousandth part of the font design
+size\index{font!design size}. Therefore, the returned picture will
+typically have a height of around 1000bp.
+
+Converting a text into plain curves is part of a process oftentimes
+called ``flattening\index{flattening}'' a document. During flattening,
+all hinting information in fonts are lost. Hinting information aid a
+rendering application in aligning certain parts of a glyph on a
+low-resolution output device. A flattened text may therefore look
+distorted on screen. In SVG output, all text is automatically
+flattened, if the internal variable
+\verb|prologues|\index{prologues?\texttt{prologues}} is set to~3 (see
+section~\ref{Dprologues}).
+
+
+\section{Macros}
+\label{macros}
+
+As alluded to earlier, MetaPost has a set of automatically included
+macros called the Plain macro package\index{Plain macros}, and some of
+the commands discussed in previous sections are defined as macros
+instead of being built into MetaPost. The purpose of this section is to
+explain how to write such macros.
+
+Macros with no arguments are very simple.
+A macro definition\index{replacement text?\tdescr{replacement text}}%
+\index{def?\texttt{def}}\index{enddef?\texttt{enddef}}
+$$ {\tt def}\, \descr{symbolic token}\, \hbox{\tt =}\,
+ \descr{replacement text}\, {\tt enddef}
+$$
+makes the \tdescr{symbolic token} an abbreviation for the
+\tdescr{replacement text}, where the \tdescr{replacement text} can be
+virtually any sequence of tokens. For example, the Plain macro package
+could almost define the {\tt fill} statement like
+this\index{fill?\texttt{fill}}:
+$$ \hbox{\tt def fill = addto currentpicture contour enddef} $$
+
+Macros with arguments are similar, except they have formal parameters
+that tell how to use the arguments in the \tdescr{replacement text}.
+For example, the {\tt
+rotatedaround}\index{rotatedaround?\texttt{rotatedaround}} macro is
+defined like this:
+$$\begin{verbatim}
+def rotatedaround(expr z, d) =
+ shifted -z rotated d shifted z enddef;
+\end{verbatim}
+$$
+The {\tt expr}\index{expr?\texttt{expr}} in this definition means that
+formal parameters {\tt z} and {\tt d} can be arbitrary expressions.
+(They should be pair expressions but the MetaPost interpreter does not
+immediately check for that.)
+
+Since MetaPost is an interpreted language, macros with arguments are a
+lot like subroutines\index{subroutines}. MetaPost macros are often used
+like subroutines, so the language includes programming concepts to
+support this. These concepts include local variables, loops, and
+conditional statements.
+
+\subsection{Grouping}
+\label{grsec}
+
+Grouping in MetaPost is essential for functions\index{functions} and
+local\index{variables!local}\index{locality} variables. The basic idea
+is that a group is a sequence of statements possibly followed by an
+expression with the provision that certain symbolic
+tokens\index{tokens!symbolic} can have their old meanings restored at
+the end of the group. If the group ends with an expression, the group
+behaves like a function call that returns that expression. Otherwise,
+the group is just a compound statement\index{compound statement}. The
+syntax for a group
+is\index{begingroup?\texttt{begingroup}}\index{endgroup?\texttt{endgroup}}
+$$ {\tt begingroup}\, \descr{statement list}\, {\tt endgroup} $$
+or
+$$ {\tt begingroup}\, \descr{statement list}\, \descr{expression}\, {\tt endgroup}
+$$
+where a \tdescr{statement list} is a sequence of statements each
+followed by a semicolon. A group with an \tdescr{expression} after the
+\tdescr{statement list} behaves like a \tdescr{primary} in
+Figure~\ref{syexpr} or like a \tdescr{numeric atom} in
+Figure~\ref{synprim}.
+
+Since the \tdescr{replacement text} for the {\tt
+beginfig}\index{beginfig?\texttt{beginfig}} macro starts with {\tt
+begingroup} and the \tdescr{replacement text} for {\tt
+endfig}\index{endfig?\texttt{endfig}} ends with {\tt endgroup}, each
+figure in a MetaPost input file behaves like a group. This is what
+allows figures can have local variables. We have already seen in
+Section~\ref{vardecl} that variable names beginning with {\tt x} or {\tt
+y} are local in the sense that they have unknown values at the beginning
+of each figure and these values are forgotten at the end of each figure.
+The following example illustrates how locality works:
+\begin{eqnarray*}
+&& \hbox{\tt x23 = 3.1;}\\
+&& \hbox{\tt beginfig(17);}\\
+&& \qquad \vdots\\
+&& \hbox{\tt y3a=1; x23=2;}\\
+&& \qquad \vdots\\
+&& \hbox{\tt endfig;}\\
+&& \hbox{\tt show x23, y3a;}
+\end{eqnarray*}
+The result of the {\tt show}\index{show?\texttt{show}} command is
+$$\begin{verbatim}
+>> 3.1
+>> y3a
+\end{verbatim}
+$$
+indicating that {\tt x23} has returned to its former value of {\tt 3.1} and
+{\tt y3a} is completely unknown as it was at {\tt beginfig(17)}.
+
+The locality of {\tt x} and {\tt y} variables is achieved by the
+statement\index{save?\texttt{save}}\label{Dsave}
+$$ \hbox{\tt save x,y} $$
+in the \tdescr{replacement text} for {\tt
+beginfig}\index{beginfig?\texttt{beginfig}}. In general, variables are
+made local by the statement
+$$ {\tt save}\, \descr{symbolic token list} $$
+where \tdescr{symbolic token list} is a comma-separated list of
+tokens:\index{tokens!symbolic}
+\begin{ctabbing}
+$\tt \descr{symbolic token list} \rightarrow \descr{symbolic token}$\\
+ $\tt \qquad \;|\; \descr{symbolic token}\hbox{\tt ,}
+ \descr{symbolic token list}$
+\end{ctabbing}
+All variables whose names begin with one of the specified symbolic
+tokens become unknown numerics and their present values are saved for
+restoration at the end of the current group. If the {\tt save}
+statement is used outside of a group, the original values are simply
+discarded.
+
+The main purpose of the {\tt save} statement is to allow macros to use
+variables without interfering with existing variables or variables in
+other calls to the same macro. For example, the predefined macro {\tt
+whatever}\index{whatever?\texttt{whatever}} has the \tdescr{replacement text}
+$$ \hbox{\tt begingroup save ?; ? endgroup} $$
+This returns an unknown numeric quantity, but it is no longer called
+question mark since that name was local to the group. Asking the name
+via {\tt show\index{show?\texttt{show}} whatever}
+yields\index{CAPSULE?\texttt{CAPSULE}}
+$$ \hbox{\verb|>> %CAPSULE|}{\it nnnn} $$
+where {\it nnnn} is an identification number that is chosen when {\tt save}
+makes the name question mark disappear.
+
+In spite of the versatility of {\tt save}, it cannot be used to make
+local changes to any of MetaPost's internal variables\index{internal
+variables}\index{variables!internal}. A statement such
+as\index{linecap?\texttt{linecap}}
+$$ \hbox{\tt save linecap} $$
+would cause MetaPost to temporarily forget the special meaning of this
+variable and just make it an unknown numeric. If you want to draw one
+dashed line with {\tt linecap:=butt} and then go back to the previous
+value, you can use the {\tt
+interim}\index{interim?\texttt{interim}}\label{Dinterm} statement as
+follows:
+\begin{eqnarray*}
+&& \hbox{\tt begingroup interim linecap:=butt;}\\
+&& {\tt draw}\, \descr{path expression}\, \hbox{\tt dashed evenly; endgroup}
+\end{eqnarray*}
+This saves the value of the
+internal variable\index{internal variables}\index{variables!internal}
+{\tt linecap} and temporarily
+gives it a new value without forgetting that {\tt linecap} is an internal
+variable. The general syntax is
+$$ {\tt interim}\, \descr{internal variable} \mathrel{\hbox{\tt:=}}
+ \descr{numeric expression} \;|\; \descr{string expression}
+$$
+
+
+\subsection{Parameterized Macros}
+
+The basic idea behind parameterized macros is to achieve greater flexibility by
+allowing auxiliary information to be passed to a macro. We have already seen
+that macro definitions can have formal parameters that represent expressions
+to be given when the macro is called. For instance a definition such as
+$$ \hbox{\tt def rotatedaround(expr z, d) = } \descr{replacement text}\,
+ {\tt enddef}
+$$
+allows the MetaPost interpreter to understand macro calls of the form
+$$\tt rotatedaround\hbox{\tt (}
+ \descr{expression}\hbox{\tt ,} \descr{expression}\hbox{\tt )}
+$$
+
+The keyword {\tt expr}\index{expr?\texttt{expr}}\index{parameter!expr}
+in the macro definition means that the parameters can be expressions of
+any type. When the definition specifies {\tt (expr z, d)}, the formal
+parameters {\tt z} and {\tt d} behave like variables of the appropriate
+types. Within the \tdescr{replacement text}, they can be used in
+expressions just like variables, but they cannot be redeclared or
+assigned to. There is no restriction against unknown or partially known
+arguments. Thus the definition\index{midpoint?\texttt{midpoint}}
+$$ \hbox{\tt def midpoint(expr a, b) = (.5[a,b]) enddef} $$
+works perfectly well when {\tt a} and {\tt b} are unknown. An
+equation such as
+$$ \hbox{\tt midpoint(z1,z2) = (1,1)} $$
+could be used to help determine {\tt z1} and {\tt z2}.
+
+Notice that the above definition for {\tt midpoint} works for numerics,
+pairs, or colors as long as both parameters have the same type. If for
+some reason we want a {\tt
+middlepoint}\index{middlepoint?\texttt{middlepoint}} macro that works
+for a single path or picture, it would be necessary to do an {\tt
+if}\index{if?\texttt{if}} test on the argument type. This uses the fact
+there is a unary operator\index{path?\texttt{path}}
+$$ {\tt path}\, \descr{primary} $$
+that returns a boolean result indicating whether its argument is a path.
+Since the basic {\tt if} test has the
+syntax\index{else?\texttt{else}}\index{fi?\texttt{fi}}
+$$ {\tt if}\, \descr{boolean expression}\hbox{\tt:}\, \descr{balanced tokens}\,
+ \hbox{\tt else:}\, \descr{balanced tokens}\, {\tt fi}
+$$
+where the \tdescr{balanced tokens}\index{balanced
+tokens?\tdescr{balanced tokens}} can be anything that is balanced with
+respect to {\tt if} and {\tt fi}, the complete {\tt
+middlepoint}\index{middlepoint?\texttt{middlepoint}} macro with type test
+looks like this:
+$$\begin{verbatim}
+def middlepoint(expr a) = if path a: (point .5*length a of a)
+ else: .5(llcorner a + urcorner a) fi enddef;
+\end{verbatim}
+$$
+The complete syntax for {\tt if} tests is shown in Figure~\ref{syif}.
+It allows multiple {\tt if} tests like
+$$ \hbox{\tt if $e_1$: \ldots\ else: if $e_2$: \ldots\ else: \ldots\ fi fi} $$
+to be shortened to\index{elseif?\texttt{elseif}}
+$$ \hbox{\tt if $e_1$: \ldots\ elseif $e_2$: \ldots\ else: \ldots\ fi} $$
+where $e_1$ and $e_2$ represent boolean expressions.
+
+Note that {\tt if} tests are not statements and the \tdescr{balanced
+tokens} in the syntax rules can be any sequence of balanced tokens even
+if they do not form a complete expression or statement. Thus we could
+have saved two tokens at the expense of clarity by defining {\tt
+middlepoint} like this:
+$$\begin{verbatim}
+def middlepoint(expr a) = if path a: (point .5*length a of
+ else: .5(llcorner a + urcorner fi a) enddef;
+\end{verbatim}
+$$
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{if test} \rightarrow if \descr{boolean expression} \hbox{\tt :}
+ \descr{balanced tokens} \descr{alternatives} fi$\\
+$\tt \descr{alternatives} \rightarrow \descr{empty}$\\
+$\tt \qquad \;|\; else\hbox{\tt :} \descr{balanced tokens}$\\
+$\tt \qquad \;|\; elseif \descr{boolean expression} \hbox{\tt :}
+ \descr{balanced tokens} \descr{alternatives}$
+\end{ctabbing}
+\caption{The syntax for {\tt if} tests.}
+\label{syif}
+\end{figure}
+
+The real purpose of macros and {\tt if} tests is to automate repetitive
+tasks and allow important subtasks to be solved separately. For
+example, Figure~\ref{fig42} uses macros \verb|draw_marked|,
+\verb|mark_angle|, and \verb|mark_rt_angle| to mark lines and angles
+that appear in the figure.
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+beginfig(42);
+pair a,b,c,d;
+b=(0,0); c=(1.5in,0); a=(0,.6in);
+d-c = (a-b) rotated 25;
+dotlabel.lft("a",a);
+dotlabel.lft("b",b);
+dotlabel.bot("c",c);
+dotlabel.llft("d",d);
+z0=.5[a,d];
+z1=.5[b,c];
+(z.p-z0) dotprod (d-a) = 0;
+(z.p-z1) dotprod (c-b) = 0;
+draw a--d;
+draw b--c;
+draw z0--z.p--z1;
+draw_marked(a--b, 1);
+draw_marked(c--d, 1);
+draw_marked(a--z.p, 2);
+draw_marked(d--z.p, 2);
+draw_marked(b--z.p, 3);
+draw_marked(c--z.p, 3);
+mark_angle(z.p, b, a, 1);
+mark_angle(z.p, c, d, 1);
+mark_angle(z.p, c, b, 2);
+mark_angle(c, b, z.p, 2);
+mark_rt_angle(z.p, z0, a);
+mark_rt_angle(z.p, z1, b);
+endfig;
+\end{verbatim}
+\quad \mathcenter{\includegraphics{mpman-42.mps}}
+$$
+\caption{MetaPost code and the corresponding figure}
+\label{fig42}
+\end{figure}
+
+The task of the
+\verb|draw_marked|\index{draw_marked?\texttt{draw\_marked}} macro is to
+draw a path with a given number of cross marks near its midpoint. A
+convenient starting place is the subproblem of drawing a single cross
+mark perpendicular to a path {\tt p} at some time {\tt t}. The
+\verb|draw_mark|\index{draw_mark?\texttt{draw\_mark}} macro in
+Figure~\ref{drawmarked} does this by first finding a vector {\tt dm}
+perpendicular to~{\tt p} at~{\tt t}. To simplify positioning the cross
+mark, the \verb|draw_marked| macro is defined to take an arc
+length\index{arc length} {\tt a} along {\tt p} and use the {\tt
+arctime}\index{arctime} operator to compute~{\tt t}
+
+With the subproblem of drawing a single mark out of the way, the
+\verb|draw_marked| macro only needs to draw the path and call
+\verb|draw_mark| with the appropriate arc length values. The
+\verb|draw_marked| macro in Figure~\ref{drawmarked} uses {\tt n}
+equally-spaced {\tt a} values centered on {\tt
+.5*arclength~p}\index{arclength?\texttt{arclength}}.
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+marksize=4pt;
+
+def draw_mark(expr p, a) =
+ begingroup
+ save t, dm; pair dm;
+ t = arctime a of p;
+ dm = marksize*unitvector direction t of p
+ rotated 90;
+ draw (-.5dm.. .5dm) shifted point t of p;
+ endgroup
+enddef;
+
+def draw_marked(expr p, n) =
+ begingroup
+ save amid;
+ amid = .5*arclength p;
+ for i=-(n-1)/2 upto (n-1)/2:
+ draw_mark(p, amid+.6marksize*i);
+ endfor
+ draw p;
+ endgroup
+enddef;
+\end{verbatim}
+$$
+\caption{Macros for drawing a path {\tt p} with {\tt n} cross marks.}
+\label{drawmarked}
+\end{figure}
+
+Since \verb|draw_marked| works for curved lines, it can be used to draw
+the arcs that the
+\verb|mark_angle|\index{mark_angle?\texttt{mark\_angle}} macro
+generates. Given points {\tt a}, {\tt b}, and {\tt c} that define a
+counter-clockwise angle at {\tt b}, the \verb|mark_angle| needs to
+generate a small arc from segment {\tt ba} to segment {\tt bc}. The
+macro definition in Figure~\ref{markangle} does this by creating an arc
+{\tt p} of radius one and then computing a scale factor {\tt s} that
+makes it big enough to see clearly.
+
+The \verb|mark_rt_angle|\index{mark_rt_angle?\texttt{mark\_rt\_angle}}
+macro is much simpler. It takes a generic right-angle corner and uses
+the {\tt zscaled}\index{zscaled?\texttt{zscaled}} operator to rotate it
+and scale it as necessary.
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+angle_radius=8pt;
+
+def mark_angle(expr a, b, c, n) =
+ begingroup
+ save s, p; path p;
+ p = unitvector(a-b){(a-b)rotated 90}..unitvector(c-b);
+ s = .9marksize/length(point 1 of p - point 0 of p);
+ if s<angle_radius: s:=angle_radius; fi
+ draw_marked(p scaled s shifted b, n);
+ endgroup
+enddef;
+
+def mark_rt_angle(expr a, b, c) =
+ draw ((1,0)--(1,1)--(0,1))
+ zscaled (angle_radius*unitvector(a-b)) shifted b
+enddef;
+\end{verbatim}
+$$
+\caption{Macros for marking angles.}
+\label{markangle}
+\end{figure}
+
+
+\subsection{Suffix and Text Parameters}
+
+Macro parameters need not always be expressions as in the previous
+examples. Replacing the keyword {\tt expr} with {\tt
+suffix}\index{suffix?\texttt{suffix}} or {\tt
+text}\index{text?\texttt{text}} in a macro definition declares the
+parameters to be variable names or arbitrary sequences of tokens. For
+example, there is a predefined macro called {\tt
+hide}\index{hide?\texttt{hide}} that takes a text
+parameter\index{parameter!text} and interprets it as a sequence of
+statements while ultimately producing an empty \tdescr{replacement
+text}. In other words, {\tt hide} executes its argument and then gets
+the next token as if nothing happened. Thus
+$$ \hbox{\tt show hide(numeric a,b; a+b=3; a-b=1) a;} $$
+prints ``\verb|>> 2|.''
+
+If the {\tt hide} macro were not predefined, it could be defined like this:
+$$\begin{verbatim}
+def ignore(expr a) = enddef;
+def hide(text t) = ignore(begingroup t; 0 endgroup) enddef;
+\end{verbatim}
+$$
+The statements represented by the text parameter {\tt t} would be
+evaluated as part of the group that forms the argument to {\tt ignore}.
+Since {\tt ignore} has an empty \tdescr{replacement text}, expansion of
+the {\tt hide} macro ultimately produces nothing.
+
+Another example of a predefined macro with a text parameter is {\tt
+dashpattern}\index{dashpattern?\texttt{dashpattern}}. The definition of
+{\tt dashpattern} starts
+$$\begin{verbatim}
+def dashpattern(text t) =
+ begingroup save on, off;
+\end{verbatim}
+$$
+then it defines {\tt on} and {\tt off} to be macros that create the desired
+picture when the text parameter~{\tt t} appears in the replacement text.
+
+Text parameters are very general, but their generality sometimes gets in
+the way. If you just want to pass a variable name to a macro, it is
+better to declare it as a suffix parameter\index{parameter!suffix}. For
+example,\index{incr?\texttt{incr}}
+$$ \hbox{\verb|def incr(suffix $) = begingroup $:=$+1; $ endgroup enddef;|} $$
+defines a macro that will take any numeric variable, add one to it, and return
+the new value. Since variable names can be more than one token long,
+$$ \hbox{\tt incr(a3b)} $$
+is perfectly acceptable if {\tt a3b} is a numeric variable. Suffix
+parameters are slightly more general than variable names because the
+definition in Figure~\ref{syvar} allows a
+\tdescr{suffix}\index{suffix?\tdescr{suffix}} to start with a
+\tdescr{subscript}\index{subscript?\tdescr{subscript}}.
+
+Figure~\ref{fig45} shows how suffix and expr parameters can be used
+together. The {\tt getmid}\index{getmid?\texttt{getmid}} macro takes a
+path variable and creates arrays of points and directions whose names
+are obtained by appending {\tt mid}, {\tt off}, and {\tt dir} to the
+path variable. The {\tt joinup}\index{joinup?\texttt{joinup}} macro
+takes arrays of points and directions and creates a path of length {\tt
+n} that passes through each {\tt pt[i]} with direction {\tt d[i]} or
+$-\hbox{\tt d[i]}$.
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+def getmid(suffix p) =
+ pair p.mid[], p.off[], p.dir[];
+ for i=0 upto 36:
+ p.dir[i] = dir(5*i);
+ p.mid[i]+p.off[i] = directionpoint p.dir[i] of p;
+ p.mid[i]-p.off[i] = directionpoint -p.dir[i] of p;
+ endfor
+enddef;
+
+def joinup(suffix pt, d)(expr n) =
+ begingroup
+ save res, g; path res;
+ res = pt[0]{d[0]};
+ for i=1 upto n:
+ g:= if (pt[i]-pt[i-1]) dotprod d[i] <0: - fi 1;
+ res := res{g*d[i-1]}...{g*d[i]}pt[i];
+ endfor
+ res
+ endgroup
+enddef;
+
+beginfig(45)
+path p, q;
+p = ((5,2)...(3,4)...(1,3)...(-2,-3)...(0,-5)...(3,-4)
+ ...(5,-3)...cycle) scaled .3cm shifted (0,5cm);
+getmid(p);
+draw p;
+draw joinup(p.mid, p.dir, 36)..cycle;
+q = joinup(p.off, p.dir, 36);
+draw q..(q rotated 180)..cycle;
+drawoptions(dashed evenly);
+for i=0 upto 3:
+ draw p.mid[9i]-p.off[9i]..p.mid[9i]+p.off[9i];
+ draw -p.off[9i]..p.off[9i];
+endfor
+endfig;
+\end{verbatim}
+\quad \mathcenter{\includegraphics{mpman-45.mps}}
+$$
+\caption{MetaPost code and the corresponding figure}
+\label{fig45}
+\end{figure}
+
+A definition that starts
+$$ \hbox{\tt def joinup(suffix pt, d)(expr n) =} $$
+might suggest that calls to the {\tt joinup} macro should have two sets of
+parentheses as in
+$$ \hbox{\tt joinup(p.mid, p.dir)(36)} $$
+instead of
+$$ \hbox{\tt joinup(p.mid, p.dir, 36)} $$
+In fact, both forms are acceptable. Parameters in a macro call can be
+separated by commas or by {\tt )(} pairs. The only restriction is that
+a text parameter\index{parameter!text} must be followed by a right
+parenthesis. For instance, a macro {\tt foo} with one text parameter
+and one expr parameter can be called
+$$ \hbox{\tt foo(a,b)(c)} $$
+in which case the text parameter is ``{\tt a,b}'' and the expr parameter is
+{\tt c}, but
+$$ \hbox{\tt foo(a,b,c)} $$
+sets the text parameter to ``{\tt a,b,c}'' and leaves the MetaPost interpreter
+still looking for the expr parameter.
+
+
+\subsection{Vardef Macros}
+
+A macro definition can begin with {\tt
+vardef}\index{vardef?\texttt{vardef}} instead of {\tt def}. Macros
+defined in this way are called vardef macros. They are particularly
+well-suited to applications where macros are being used like functions
+or subroutines. The main idea is that a vardef macro is like a variable
+of type ``macro.''
+
+Instead of {\tt def} \tdescr{symbolic token}, a vardef macro begins
+$$ {\tt vardef}\, \descr{generic variable} $$
+where a \tdescr{generic variable}\index{generic variable?\tdescr{generic
+variable}} is a variable name with numeric subscripts replaced by the
+generic subscript\index{subscript!generic} symbol {\tt
+[]}\index{[]?\texttt{[]}!vardef macro?\texttt{vardef} macro}. In other
+words, the name following {\tt
+vardef} obeys exactly the same syntax as the name given in a variable
+declaration. It is a sequence of tags and generic subscript symbols
+starting with a tag, where a tag\index{tags} is a symbolic token that is
+not a macro or a primitive operator as explained in
+Section~\ref{vardecl}.
+
+The simplest case is when the name of a vardef macro consists of a
+single tag. Under such circumstances, {\tt def} and {\tt vardef}
+provide roughly the same functionality. The most obvious difference is
+that {\tt begingroup}\index{begingroup?\texttt{begingroup}} and {\tt
+endgroup}\index{endgroup?\texttt{endgroup}} are automatically inserted
+at the beginning and end of the \tdescr{replacement text} of every
+vardef macro. This makes the \tdescr{replacement text} a group so that
+a vardef macro behaves like a subroutine or a function call.
+
+Another property of vardef macros is that they allow multi-token macro
+names and macro names involving generic subscripts. When a vardef macro
+name has generic subscripts, numeric values have to be given when the
+macro is called. After a macro definition
+$$ \hbox{\tt vardef a[]b(expr p) =}\, \descr{replacement text}\,
+ \hbox{\tt enddef;}
+$$
+{\tt a2b((1,2))} and {\tt a3b((1,2)..(3,4))} are macro calls. But how
+can the \tdescr{replacement text} tell the difference between {\tt a2b}
+and {\tt a3b}? Two implicit suffix parameters\index{parameter!suffix}
+are automatically provided for this purpose. Every vardef macro has
+suffix parameters \verb|#@|\index{#@?\texttt{\#@}} and
+\verb|@|\index{@?\texttt{@}}, where \verb|@| is the last token in the
+name from the macro call and \verb|#@| is everything preceding the last
+token. Thus \verb|#@| is {\tt a2} when the name is given as {\tt a2b}
+and {\tt a3} when the name is given as {\tt a3b}.
+
+Suppose, for example, that the {\tt a[]b} macro is to take its argument
+and shift it by an amount that depends on the macro name. The macro
+could be defined like this:
+$$ \hbox{\verb|vardef a[]b(expr p) = p shifted (#@,b) enddef;|} $$
+Then {\tt a2b((1,2))} means {\tt (1,2) shifted (a2,b)}
+and {\tt a3b((1,2)..(3,4))} means
+$$ \hbox{\tt ((1,2)..(3,4)) shifted (a3,b)}. $$
+
+If the macro had been {\tt a.b[]}, \verb|#@| would always be {\tt a.b}
+and the \verb|@| parameter would give the numeric subscript. Then {\tt
+a@} would refer to an element of the array {\tt a[]}. Note that
+\verb|@| is a suffix parameter, not an expr parameter, so an expression
+like {\tt @+1} would be illegal. The only way to get at the numeric
+values of subscripts in a suffix parameter\index{parameter!suffix} is by
+extracting them from the string returned by the {\tt
+str}\index{str?\texttt{str}}\label{Dstr} operator. This operator takes
+a suffix and returns a string representation of a suffix. Thus {\tt str
+@} would be \verb|"3"| in {\tt a.b3} and \verb|"3.14"| in {\tt a.b3.14}
+or {\tt a.b[3.14]}. Since the syntax for a
+\tdescr{suffix}\index{suffix?\tdescr{suffix}} in Figure~\ref{syvar}
+requires negative subscripts to be in brackets, {\tt str @} returns {\tt
+"[-3]"} in {\tt a.b[-3]}.
+
+The {\tt str} operator is generally for emergency use only. It is
+better to use suffix parameters only as variable names or suffixes. The
+best example of a vardef macro involving suffixes is the {\tt z} macro
+that defines the {\tt z} convention\index{z convention?{\tt z}
+convention}. The definition involves a special token
+\verb|@#|\index{@#?\texttt{@\#}} that refers to the suffix following the
+macro name:
+$$ \hbox{\verb|vardef z@#=(x@#,y@#) enddef;|} $$
+This means that any variable name whose first token is {\tt z} is
+equivalent to a pair of variables whose names are obtained by replacing
+{\tt z} with {\tt x} and~{\tt y}. For instance, {\tt z.a1} calls the
+{\tt z} macro with the suffix parameter \verb|@#| set to {\tt a1}.
+
+In general,
+$$ {\tt vardef}\, \descr{generic variable} \hbox{\verb|@#|} $$
+is an alternative to {\tt vardef} \tdescr{generic variable} that causes the
+MetaPost interpreter
+to look for a suffix following the name given in the macro call and makes this
+available as the \verb|@#| suffix parameter.
+
+To summarize the special features of vardef macros, they allow a broad
+class of macro names as well as macro names followed by a special suffix
+parameter. Furthermore, {\tt begingroup} and {\tt endgroup} are
+automatically added to the \tdescr{replacement text} of a vardef macro.
+Thus using {\tt vardef} instead of {\tt def} to define the {\tt
+joinup}\index{joinup?\texttt{joinup}} macro in Figure~\ref{fig45} would
+have avoided the need to include {\tt begingroup} and {\tt endgroup}
+explicitly in the macro definition.
+
+In fact, most of the macro definitions given in previous examples could
+equally well use {\tt vardef} instead of {\tt def}. It usually does not
+matter very much which you use, but a good general rule is to use {\tt
+vardef} if you intend the macro to be used like a function or a
+subroutine. The following comparison should help in deciding when to
+use {\tt vardef}.
+
+\begin{itemize}
+\item Vardef macros are automatically surrounded by {\tt begingroup}
+and {\tt endgroup}.
+\item The name of a vardef macro can be more than one token long and it can
+contain subscripts.
+\item A vardef macro can have access to the suffix that follows the macro name
+when the macro is called.
+\item When a symbolic token is used in the name of a vardef macro it remains
+a tag\index{tags} and can still be used in other variable names. Thus
+{\tt p5dir} is a legal variable name even though {\tt dir} is a vardef
+macro, but an ordinary macro such as {\tt ...}\index{...?\texttt{...}}
+cannot be used in a variable name. (This is fortunate since {\tt
+z5...z6} is supposed to be a path expression, not an elaborate variable
+name).
+\end{itemize}
+
+
+\subsection{Defining Unary and Binary Macros}
+
+It has been mentioned several times that some of the operators and
+commands discussed so far are actually predefined macros. These include
+unary operators such as {\tt round}\index{round?\texttt{round}} and {\tt
+unitvector}\index{unitvector?\texttt{unitvector}}, statements such as
+{\tt fill}\index{fill?\texttt{fill}} and {\tt
+draw}\index{draw?\texttt{draw}}, and binary operators such as {\tt
+dotprod}\index{dotprod?\texttt{dotprod}} and {\tt
+intersectionpoint}\index{intersectionpoint?\texttt{intersectionpoint}}.
+The main difference between these macros and the ones we already know
+how to define is their argument syntax.
+
+The {\tt round} and {\tt unitvector} macros are examples of what
+Figure~\ref{syexpr} calls \tdescr{unary op}. That is, they are followed
+by a primary expression. To specify a macro argument of this type, the
+macro definition should look like this:
+$$ \hbox{\tt vardef round primary u =}\, \descr{replacement text}\,
+ \hbox{\tt enddef;}
+$$
+The {\tt u} parameter is an expr parameter\index{parameter!expr} and it can be
+used exactly like the expr parameter defined using the ordinary
+$$ \hbox{\tt (expr u)} $$
+syntax.
+
+As the {\tt round} example suggests, a macro can be defined to take a
+\tdescr{secondary}\index{secondary?\tdescr{secondary}},
+\tdescr{tertiary}\index{tertiary?\tdescr{tertiary}}, or an
+\tdescr{expression}\index{expression?\tdescr{expression}} parameter.
+For example, the predefined definition of the {\tt fill} macro is
+roughly\index{fill?\texttt{fill}}
+$$ \hbox{\tt def fill expr c = addto currentpicture contour c enddef;} $$
+
+It is even possible to define a macro to play the role of \tdescr{of
+operator}\index{of operator?\tdescr{of operator}} in
+Figure~\ref{syexpr}. For example, the {\tt direction
+of}\index{direction of?\texttt{direction of}} macro has a definition of
+this form:
+$$ \hbox{\tt vardef direction expr t of p =}\, \descr{replacement text}\,
+ \hbox{\tt enddef;}
+$$
+
+Macros can also be defined to behave like binary operators. For instance, the
+definition of the {\tt dotprod} macro has the
+form\index{dotprod?\texttt{dotprod}}\index{primarydef?\texttt{primarydef}}
+$$ \hbox{\tt primarydef w dotprod z =}\, \descr{replacement text}\,
+ \hbox{\tt enddef;}
+$$
+This makes {\tt dotprod} a \tdescr{primary binop}\index{primary
+binop?\tdescr{primary binop}}. Similarly, {\tt
+secondarydef}\index{secondarydef?\texttt{secondarydef}} and {\tt
+tertiarydef}\index{tertiarydef?\texttt{tertiarydef}} introduce
+\tdescr{secondary binop}\index{secondary binop?\tdescr{secondary binop}}
+and \tdescr{tertiary binop}\index{tertiary binop?\tdescr{tertiary
+binop}} definitions. These all define ordinary macros, not vardef
+macros; e.g., there is no ``{\tt primaryvardef}.''
+
+Thus macro definitions can be introduced by {\tt def}, {\tt vardef},
+{\tt primarydef}, {\tt secondarydef}, or {\tt tertiarydef}. A
+\tdescr{replacement text}\index{replacement text?\tdescr{replacement
+text}} is any list of tokens that is balanced with respect to {\tt
+def}-{\tt enddef} pairs where all five macro definition tokens are
+treated like {\tt def} for the purpose of {\tt def}-{\tt enddef}
+matching.
+
+The rest of the syntax for macro definitions is summarized in
+Figure~\ref{symacro}. The syntax contains a few surprises. The macro
+parameters can have a \tdescr{delimited part} and an \tdescr{undelimited
+part}. Normally, one of these is \tdescr{empty}, but it is possible to
+have both parts nonempty:
+$$ \hbox{\tt def foo(text a) expr b =}\, \descr{replacement text}\,
+ \hbox{\tt enddef;}
+$$
+This defines a macro {\tt foo} to take a text parameter in parentheses followed
+by an expression.
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{macro definition} \rightarrow
+ \descr{macro heading} \hbox{\tt =} \descr{replacement text}\, enddef$\\
+$\tt \descr{macro heading} \rightarrow def\, \descr{symbolic token}
+ \descr{delimited part} \descr{undelimited part}$\\
+$\tt \qquad \;|\; vardef\, \descr{generic variable} \descr{delimited part}
+ \descr{undelimited part}$\\
+$\tt \qquad \;|\; vardef\, \descr{generic variable} \hbox{\tt @\#}
+ \descr{delimited part} \descr{undelimited part}$\\
+$\tt \qquad \;|\; \descr{binary def} \descr{parameter}
+ \descr{symbolic token} \descr{parameter}$\\
+$\tt \descr{delimited part} \rightarrow \descr{empty}$\\
+$\tt \qquad \;|\; \descr{delimited part}
+ \hbox{\tt (}\descr{parameter type} \descr{parameter tokens}\hbox{\tt )}$\\
+$\tt \descr{parameter type} \rightarrow expr \;|\; suffix \;|\; text$\\
+$\tt \descr{parameter tokens} \rightarrow \descr{parameter} \;|\;
+ \descr{parameter tokens}\hbox{\tt ,} \descr{parameter}$\\
+$\tt \descr{parameter} \rightarrow \descr{symbolic token}$\\
+$\tt \descr{undelimited part} \rightarrow \descr{empty}$\\
+$\tt \qquad \;|\; \descr{parameter type} \descr{parameter}$\\
+$\tt \qquad \;|\; \descr{precedence level} \descr{parameter}$\\
+$\tt \qquad \;|\; expr\, \descr{parameter}\, of\, \descr{parameter}$\\
+$\tt \descr{precedence level} \rightarrow primary \;|\; secondary \;|\;
+ tertiary$\\
+$\tt \descr{binary def} \rightarrow primarydef \;|\; secondarydef \;|\;
+ tertiatydef$
+\end{ctabbing}
+\caption{The syntax for macro definitions}
+\label{symacro}
+\end{figure}
+
+The syntax also allows the \tdescr{undelimited part} to specify an
+argument type of {\tt suffix}\index{suffix?\texttt{suffix}} or {\tt
+text}\index{text?\texttt{text}}. An example of a macro with an
+undelimited suffix parameter\index{parameter!suffix} is the predefined
+macro {\tt incr}\index{incr?\texttt{incr}}\label{Dincr} that is actually
+defined like this:
+$$ \hbox{\verb|vardef incr suffix $ = $:=$+1; $ enddef;|} $$
+This makes {\tt incr} a function that takes a variable, increments it,
+and returns the new value. Undelimited suffix parameters may be
+parenthesized, so {\tt incr a} and {\tt incr(a)} are both legal if {\tt
+a} is a numeric variable. There is also a similar predefined macro {\tt
+decr}\index{decr?\texttt{decr}} that subtracts~1.
+
+Undelimited text parameters\index{parameter!text} run to the end of a
+statement. More precisely, an undelimited text parameter is the list of
+tokens following the macro call up to the first ``{\tt
+;}\index{semicolon}'' or ``{\tt
+endgroup}\index{endgroup?\texttt{endgroup}}'' or ``{\tt
+end}\index{end?\texttt{end}}'' except that an argument containing ``{\tt
+begingroup}'' will always include the matching ``{\tt endgroup}.'' An
+example of an undelimited text parameter comes from the predefined macro
+{\tt cutdraw}\index{cutdraw?\texttt{cutdraw}}\label{Dctdraw} whose
+definition is
+roughly\index{linecap?\texttt{linecap}}\index{butt?\texttt{butt}}\index{interim?\texttt{interim}}
+$$\begin{verbatim}
+def cutdraw text t =
+ begingroup interim linecap:=butt; draw t; endgroup enddef;
+\end{verbatim}
+$$
+This makes {\tt cutdraw} synonymous with {\tt draw} except for the {\tt
+linecap} value. (This macro is provided mainly for compatibility with
+\MF\index{metafont?\MF}.)
+
+
+\section{Loops}
+
+Numerous examples in previous sections have used simple {\tt for} loops of the
+form\index{loops}\index{for?\texttt{for}}\index{endfor?\texttt{endfor}}
+$$ {\tt for}\, \descr{symbolic token}\, \hbox{\tt =}\,
+ \descr{expression}\, {\tt upto}\, \descr{expression}:\
+ \descr{loop text}\, {\tt endfor}
+$$
+It is equally simple to construct a loop that counts downward: just
+replace {\tt upto} by {\tt
+downto}\index{downto?\texttt{downto}}\label{Ddwnto} make the second
+\tdescr{expression} smaller than the first. This section covers more
+complicated types of progressions, loops where the loop counter behaves
+like a suffix parameter, and ways of exiting from a loop.
+
+The first generalization is suggested by the fact that {\tt
+upto}\index{upto?\texttt{upto}} is a predefined macro
+for\index{step?\texttt{step}}\index{until?\texttt{until}}
+$$ \hbox{\tt step 1 until} $$
+and {\tt downto}\index{downto?\texttt{downto}} is a macro for {\tt step
+-1 until}. A loop begining
+$$ \hbox{\tt for i=a step b until c} $$
+scans a sequence of {\tt i} values {\tt a}, ${\tt a}+{\tt b}$, ${\tt
+a}+2{\tt b}$, \ldots, stopping before {\tt i} passes {\tt c}; i.e., the
+loop scans {\tt i} values where ${\tt i}\le {\tt c}$ if ${\tt b}>0$ and
+${\tt i}\ge {\tt c}$ if ${\tt b}<0$. For ${\tt b}=0$ the loop never
+terminates, even if ${\tt a}={\tt c}$.
+
+It is best to use this feature only when the step size is an integer or
+some number that can be represented exactly in fixed point
+arithmetic\index{arithmetic} as a multiple of $1\over65536$. Otherwise,
+error will accumulate and the loop index might not reach the expected
+termination value. For instance,
+$$ \hbox{\tt for i=0 step .1 until 1: show i; endfor} $$
+shows ten {\tt i} values the last of which is 0.90005.
+
+The standard way of avoid the problems associated with non-integer step
+sizes is to iterate over integer values and then multiply by a scale
+factor when using the loop index as was done in Figures \ref{fig1}
+and~\ref{fig40}.
+
+Alternatively, the values to iterate over can be given explicitly. Any
+sequence of zero or more expressions separated by commas can be used in
+place of {\tt a step b upto c}. In fact, the expressions need not all
+be the same type and they need not have known values. Thus
+$$ \hbox{\tt for t=3.14, 2.78, (a,2a), "hello": show t; endfor} $$
+shows the four values listed.
+
+Note that the loop body in the above example is a statement followed by a
+semicolon. It is common for the body of a loop to be one or more statements,
+but this need not be the case. A loop is like a macro definition followed by
+calls to the macro. The loop body can be virtually any sequence of tokens as
+long as they make sense together. Thus, the (ridiculous) statement
+$$ \hbox{\verb|draw for p=(3,1),(6,2),(7,5),(4,6),(1,3): p-- endfor cycle;|} $$
+is equivalent to
+$$ \hbox{\verb|draw (3,1)--(6,2)--(7,5)--(4,6)--(1,3)--cycle;|} $$
+(See Figure~\ref{fig17} for a more realistic example of this.)
+
+If a loop is like a macro definition, the loop index is like an expr
+parameter\index{parameter!expr}. It can represent any value, but it is
+not a variable and it cannot be changed by an assignment
+statement\index{assignment}. In order to do that, you need a {\tt
+forsuffixes}\index{forsuffixes?\texttt{forsuffixes}} loop. A {\tt
+forsuffixes} loop is a lot like a {\tt for} loop, except the loop index
+behaves like a suffix parameter\index{parameter!suffix}. The syntax is
+$$ {\tt forsuffixes}\, \descr{symbolic token}\, \hbox{\tt =}\,
+ \descr{suffix list}:\ \descr{loop text}\, {\tt endfor}
+$$
+where a \tdescr{suffix list} is a comma-separated list of suffixes. If
+some of the suffixes are \tdescr{empty}, the \tdescr{loop text} gets
+executed with the loop index parameter set to the empty suffix.
+
+A good example of a {\tt forsuffixes} loop is the definition of the {\tt
+dotlabels}\index{dotlabels?\texttt{dotlabels}}
+macro\index{str?\texttt{str}}:
+$$\begin{verbatim}
+vardef dotlabels@#(text t) =
+ forsuffixes $=t: dotlabel@#(str$,z$); endfor enddef;
+\end{verbatim}
+$$
+This should make it clear why the parameter to {\tt dotlabels} has to be a
+comma-separated list of suffixes. Most macros that accept variable-length
+comma-separated lists
+use them in {\tt for} or {\tt forsuffixes} loops in this fashion as values to
+iterate over.
+
+When there are no values to iterate over, you can use a
+{\tt forever}\index{forever?\texttt{forever}} loop:
+$$ {\tt forever}\hbox{\tt :}\, \descr{loop text}\, {\tt endfor} $$
+To terminate such a loop when a boolean condition becomes true, use an exit
+clause\index{exitif?\texttt{exitif}}:
+$$ {\tt exitif}\, \descr{boolean expression} \hbox{\tt ;} $$
+When the MetaPost interpreter encounters an exit clause, it evaluates
+the \tdescr{boolean expression} and exits the current loop if the
+expression is true. If it is more convenient to exit the loop when an
+expression becomes false, use the predefined macro {\tt
+exitunless}\index{exitunless?\texttt{exitunless}}.
+
+Thus MetaPost's version of a {\bf while} loop is
+$$ \hbox{\tt forever: exitunless}\, \descr{boolean expression} \hbox{\tt ;}\,
+ \descr{loop text}\, {\tt endfor}
+$$
+The exit clause could equally well come just before {\tt endfor} or anywhere
+in the \tdescr{loop text}. In fact any {\tt for}, {\tt forever}, or
+{\tt forsuffixes} loop can contain any number of exit clauses.
+
+The summary of loop syntax shown in Figure~\ref{syloop} does not mention
+exit clauses explicitly because a \tdescr{loop text} can be virtually
+any sequence of tokens. The only restriction is that a \tdescr{loop
+text} must be balanced with respect to {\tt for} and {\tt endfor}. Of
+course this balancing process treats {\tt forsuffixes} and {\tt forever}
+just like {\tt for}.
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{loop} \rightarrow \descr{loop header}\hbox{\tt :}\,
+ \descr{loop text} endfor$\\
+$\tt \descr{loop header} \rightarrow for\, \descr{symbolic token}\,
+ \hbox{\tt =}\, \descr{progression}$\\
+$\tt \qquad \;|\; for\, \descr{symbolic token}\, \hbox{\tt =}\,
+ \descr{for list}$\\
+$\tt \qquad \;|\; forsuffixes\, \descr{symbolic token}\, \hbox{\tt =}\,
+ \descr{suffix list}$\\
+$\tt \qquad \;|\; forever$\\
+$\tt \descr{progression} \rightarrow \descr{numeric expression}\, upto\,
+ \descr{numeric expression}$\\
+$\tt \qquad \;|\; \descr{numeric expression}\, downto\,
+ \descr{numeric expression}$\\
+$\tt \qquad \;|\; \descr{numeric expression}\, step\,
+ \descr{numeric expression}\, until\, \descr{numeric expression} $\\
+$\tt \descr{for list} \rightarrow \descr{expression}
+ \;|\; \descr{for list}\hbox{\tt ,}\, \descr{expression}$\\
+$\tt \descr{suffix list} \rightarrow \descr{suffix}
+ \;|\; \descr{suffix list}\hbox{\tt ,}\, \descr{suffix}$
+\end{ctabbing}
+\caption{The syntax for loops}
+\label{syloop}
+\end{figure}
+
+
+\section{Reading and Writing Files}
+File access was one of the new language features introduced in version~0.60
+of the MetaPost language. A new operator
+$$ {\tt readfrom}\ \descr{file name} $$\index{readfrom?\texttt{readfrom}}\label{Dreadfrom}%
+returns a string giving the next line of input from the named
+file\index{files!reading}. The \tdescr{file name} can be any primary
+expression of type string. If the file has ended or cannot be read, the
+result is a string consisting of a single null character. The preloaded
+{\tt plain} macro package introduces the name
+{\tt EOF}\index{EOF?\texttt{EOF}}\label{Deof} for this string. After
+{\tt readfrom} has returned {\tt EOF}, additional reads from the same file
+cause the file to be reread from the start.
+
+All files opened by \ttt{readfrom} that have not completely been read
+yet are closed\index{files!closing} automatically when the program
+terminates, but there exists a command
+$${\tt closefrom}\ \descr{file name}$$%
+\index{closefrom?\texttt{closefrom}}\label{Dclosefrom}%
+to close files opened by {\tt readfrom} explicitly. It is wise to
+manually close files you do not need to read completely (i.e. until {\tt
+ EOF} is returned) because otherwise such files will continue to use
+internal resources and perhaps cause a \ttt{capacity exceeded!} error.
+
+The opposite of {\tt readfrom} is the command
+$$ {\tt write}\ \descr{string expression}\ {\tt to}\ \descr{file name} $$%
+\index{write to?\texttt{write to}}\label{Dwrite}%
+This writes\index{files!writing} a line of text to the specified output file,
+opening the file first if necessary. All such files are
+closed\index{files!closing} automatically when the program terminates. They
+can also be closed explicitly by using {\tt EOF}\index{EOF?\texttt{EOF}}
+as the \tdescr{string expression}. The only way to tell if a {\tt write}
+command has succeeded is to close the file and use {\tt readfrom} to look
+at it.
+
+
+\section{Utility Routines}
+
+\index{utility routines}
+\index{mplib?\texttt{mplib}}
+\index{metapost/base?\texttt{metapost/base}}
+
+This section describes some of the utility routines included in the
+\texttt{mplib} directory of the development source hierarchy. Future
+versions of this documentation may include more; meanwhile, please read
+the source files, most have explanatory comments at the top. They are
+also included in the MetaPost and larger \TeX\ distributions, typically
+in a \texttt{texmf/metapost/base} directory.
+
+
+\subsection{\texttt{TEX.mp}}
+
+\label{dTEX}
+\index{TEX.mp?\texttt{TEX.mp}}
+\index{labels, with variable text}
+\index{string expressions, as labels}
+
+\texttt{TEX.mp} provides a way to typeset the text of a MetaPost string
+expression. Suppose, for example, you need labels of the form $n_0$,
+$n_1$, \ldots, $n_{10}$ across the $x$ axis. You can do this (relatively)
+conveniently with \texttt{TEX.mp}, as follows:
+$$\begin{verbatim}
+input TEX;
+beginfig(100)
+ last := 10;
+ for i := 0 upto last:
+ label(TEX("$n_{" & decimal(i) & "}$"), (5mm*i,0));
+ endfor
+ ...
+endfig;
+\end{verbatim}
+$$
+In contrast, the basic \texttt{btex} command (see p.\ \pageref{Dbtex})
+typesets verbatim text. That is, \texttt{btex~s~etex} typesets the
+literal character `s'; \texttt{TEX(s)} typesets the value of the
+MetaPost text variable~$s$.
+
+\index{LaTeX?\LaTeX!typesetting labels with} In version 0.9,
+\texttt{TEX.mp} acquired two additional routines to facilitate using
+\LaTeX\ to typeset labels: \texttt{TEXPRE} and \texttt{TEXPOST}. Their
+values are remembered, and included before and after (respectively) each
+call to \texttt{TEX}. Otherwise, each \texttt{TEX} call is effectively
+typeset independently. \texttt{TEX} calls also do not interfere with
+uses of {\tt verbatimtex}\index{verbatimtex?\texttt{verbatimtex}} (p.\
+\pageref{Dverbatimtex}).
+
+Here's the same example as above, using the \LaTeX\ commands \verb|\(|
+and \verb|\)|:
+
+$$\begin{verbatim}
+input TEX;
+TEXPRE("%&latex" & char(10) & "\documentclass{article}\begin{document}");
+TEXPOST("\end{document}");
+beginfig(100)
+ last := 10;
+ for i := 0 upto last:
+ label(TEX("\( n_{" & decimal(i) & "} \)"), (5mm*i,0));
+ endfor
+ ...
+endfig;
+\end{verbatim}
+$$
+Explanation:
+\begin{itemize}
+
+\item
+The \texttt{\%\&latex}\index{\%?\texttt{\%}!magic comment!\%\&?\texttt{\%\&}} causes \LaTeX\ to be invoked instead of \TeX.
+(See below, also.) Web2C- and MiKTeX-based \TeX\ implementations, at
+least, understand this \texttt{\%\&} specification; see, e.g., the Web2C
+documentation for details, \url{http://tug.org/web2c}. (Information on
+how to do the same with other systems would be most welcome.)
+
+\item
+The \texttt{char(10)} puts a newline (ASCII character code 10, decimal)
+in the output.
+
+\item
+The \verb|\documentclass...| is the usual way to start a \LaTeX\
+document.
+
+\item
+The \verb|TEXPOST("\end{document}")| is not strictly necessary, due to
+the behavior of \texttt{mpto}, but it is safer to include it.
+
+\end{itemize}
+
+Unfortunately, \TeX\ \verb|\special| instructions vanish in this
+process. So it is not possible to use packages such as \texttt{xcolor}
+and \texttt{hyperref}.
+
+In case you're curious, these routines are implemented very simply: they
+write \texttt{btex} commands to a temporary file and then use
+\texttt{scantokens} (p.\ \pageref{Dscantokens}) to process it. The
+\texttt{makempx} mechanism (p.\ \pageref{Dmakempx}) does all the work of
+running \TeX.
+
+The \verb|%&| magic on the first line is not the only way to specify
+invoking a different program than (plain) \TeX. It has the advantage of
+maximum flexibility: different \texttt{TEX} constructs can use different
+\TeX\ processors. But at least two other methods are possible:
+
+\begin{itemize}
+\item Set the environment variable \texttt{TEX} to \texttt{latex}---or
+whatever processor you want to invoke. (To handle \ConTeXt\ fragments,
+\ttt{texexec} could be used.) This might be convenient when writing a
+script, or working on a project that always requires \texttt{latex}.
+
+\item Invoke MetaPost with the command-line option \ttt{-tex=latex} (or
+whatever processor, of course). This might be useful from a Makefile,
+or just a one-off run.
+\end{itemize}
+
+
+\section{Another Look at the MetaPost Workflow}
+\label{workflow2}
+
+\index{workflow}
+
+In Section~\ref{workflow} we already had a brief look at how MetaPost
+compiles input files and generates output files. This section contains
+some more information and discusses internal variables that can be used
+to control MetaPost's run-time behavior, previewing PostScript output,
+debugging MetaPost code, and importing MetaPost graphics into
+third-party applications.
+
+\subsection{Customizing Run-Time Behavior}
+
+\index{runtime behavior!customize}
+
+MetaPost knows and obeys a number of internal\index{internal
+ variables}\index{variables!internal} variables that have no direct
+impact on drawing commands, but can be used to customize the way the
+MetaPost compiler processes input files. The following paragraphs
+describe those variables (in no particular order).
+
+\paragraph{Date and Time}
+
+MetaPost provides a number of internal numeric variables that store the
+date and time a job was started, i.e., the MetaPost executable was
+called on the command-line. Variables
+\texttt{year}\index{year?\texttt{year}}\label{Dyear},
+\texttt{month}\index{month?\texttt{month}}\label{Dmonth},
+\texttt{day}\index{day?\texttt{day}}\label{Dday},
+\texttt{hour}\index{hour?\texttt{hour}}\label{Dhour}, and
+\texttt{minute}\index{minute?\texttt{minute}}\label{Dminute} should be
+self-explanatory. Variable
+\texttt{time}\index{time?\texttt{time}}\label{Dtime} returns the number
+of minutes past midnight, since the job was started, i.e.,
+$\texttt{time} = 60*\texttt{hour} + \texttt{minute}$.
+
+\paragraph{Output File Names}
+
+As discussed in Section~\ref{workflow}, by default, every
+\verb|beginfig| \ldots\ \verb|endfig| group in an input file corresponds
+to an output file that follows the naming scheme
+\texttt{\tdescr{jobname}.\tdescr{n}}. That is, all files have varying
+numeric file extensions. MetaPost provides a template mechanism that
+allows for more flexible output file names. The template mechanism uses
+\texttt{printf}-style escape sequences that are re-evaluated at ship-out
+time, i.e., before each figure is written to disk.
+
+To configure the output file naming scheme a string containing the
+corresponding escape sequences has to be assigned to the internal string
+variable
+\verb|outputtemplate|\index{outputtemplate?\texttt{outputtemplate}}\label{Doutputtemplate}.
+The escape sequences provided are listed in
+table~\ref{tab:outputtemplate}. As an example, if this code is saved in
+a file \texttt{fig.mp},
+$$
+\begin{verbatim}
+outputtemplate := "%j-%c.mps";
+beginfig(1);
+ drawdot origin;
+endfig;
+end
+\end{verbatim}
+$$
+it will create the output file \texttt{fig-1.mps} instead of
+\texttt{fig.1}. The file extension \texttt{mps}\index{mps file?{\tt
+ mps} file}\index{files!mps?{\tt mps}} is conventionally chosen for
+MetaPost's PostScript output (see Section~\ref{mpimport}). For SVG and
+PNG output one would want to use file extensions \texttt{svg}\index{svg
+ file?{\tt svg} file}\index{files!svg?{\tt svg}} and
+\texttt{png}\index{png file?{\tt png} file}\index{files!png?{\tt png}}
+instead.
+
+\begin{table}
+ \centering
+ \begin{tabular}{|>{\ttfamily}l|l|>{\ttfamily}l|}
+ \hline
+ \multicolumn1{|c|}{Escape sequence} & \multicolumn1{c|}{Meaning} & \multicolumn1{c|}{Alternative}\\\hline
+ \%\%\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%\%?\texttt{\%\%}} & percent sign &\\
+ \%\{\tdescr{internal variable}\}\index{\%?\texttt{\%}!outputtemplate
+ escape sequence?\texttt{outputtemplate} escape sequence!\%\{...\}?\texttt{\%\{\tdescr{internal variable}\}}} & evaluate internal variable &\\
+ \%j\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%j?\texttt{\%j}} & current jobname & \%\{jobname\}\\
+ \%c\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%c?\texttt{\%c}} & charcode value (\texttt{beginfig} argument) & \%\{charcode\}\\
+ \%y\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%y?\texttt{\%y}} & current year & \%\{year\}\\
+ \%m\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%m?\texttt{\%m}} & month (numeric) & \%\{month\}\\
+ \%d\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%d?\texttt{\%d}} & day of the month & \%\{day\}\\
+ \%H\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%H?\texttt{\%H}} & hour & \%\{hour\}\\
+ \%M\index{\%?\texttt{\%}!outputtemplate escape sequence?\texttt{outputtemplate} escape sequence!\%M?\texttt{\%M}} & minute & \%\{minute\}\\
+ \hline
+ \end{tabular}
+ \caption{Allowed escape sequences for \ttt{outputtemplate}}
+ \label{tab:outputtemplate}
+\end{table}
+
+In single-letter escape sequences referring to internal numerics, the
+corresponding value is rounded to the nearest integer before it is
+converted to a string expression. In such escape sequences, a number
+from the range 0 to~99 can optionally be placed directly after \verb|%|
+that determines the minimum number of digits in the resulting string
+expression, like \verb|%2m|. If the decimal representation of the
+internal variable requires more digits, actual string length will exceed
+the requested length. If less digits are required, the string is padded
+to the requested length with zeros from left.
+
+In single-letter escape sequences referring to internal string
+variables, like \verb|%j|, and in the \verb|%{...}| escape sequence,
+neither rounding nor zero-padding take place.
+
+For backwards compatibility, the
+\verb|%c|\index{\%?\texttt{\%}!outputtemplate escape
+ sequence?\texttt{outputtemplate} escape sequence!\%c?\texttt{\%c}}
+escape sequence is handled special. If the result of rounding the
+charcode value is negative, \verb|%c| evaluates to the string \verb|ps|.
+This transformation can be bypassed by using \verb|%{charcode}| instead
+of \verb|%c|. But note, that this bypasses rounding and zero-padding as
+well.
+
+The template mechanism can also be used for naming graphic files
+individually, yet keeping all sources in one file. Collecting, e.g.,
+different diagram sources in a single file \texttt{fig.mp}, it might be
+easier to recall the correct diagram names in a \TeX\ document than with
+numbered file names. Note, the argument to \verb|beginfig| is not
+relevant as long as there's no \verb|%c| pattern in the file name
+template string.
+$$
+\begin{verbatim}
+outputtemplate := "fig-quality.mps";
+beginfig(1);
+ ...
+endfig;
+
+outputtemplate := "fig-cost-vs-productivity.mps";
+beginfig(2);
+ ...
+endfig;
+\end{verbatim}
+$$
+
+To ensure compatibility with older files, the default value of
+\verb|outputtemplate| is \verb|%j.%c|. If you assign an empty string,
+it will revert to that default. MetaPost versions~1.000 to~1.102 used a
+different template mechanism, see Section~\ref{Dfilenametemplate} for
+more information.
+
+During \texttt{shipout}\index{shipout?\texttt{shipout}}, the name of the
+output file to be written is stored in an internal string variable
+\texttt{outputfilename}\index{outputfilename?\texttt{outputfilename}}\label{Doutputfilename}.
+It remains available until the next \texttt{shipout} command. The
+variable is initially empty.
+
+\paragraph{Output Format}
+
+MetaPost can generate graphics in three output formats:
+
+\begin{itemize}
+\item Encapsulated PostScript\index{PostScript!structured}
+ (EPSF\index{EPSF}),
+\item Scalable Vector Graphics (SVG\index{SVG}) following version~1.1 of
+ the SVG specification~\cite{w3c:svg1.1} (since MetaPost version
+ 1.200),
+\item Portable Network Graphics (PNG), a losslessly compressing bitmap
+ format (since MetaPost version 1.800).
+\end{itemize}
+By default, MetaPost outputs PostScript files---hence the name MetaPost.
+The output format can be changed by assigning values \verb|"svg"| or
+\verb|"png"| to the internal string variable\index{internal
+ variables}\index{variables!internal}
+\verb|outputformat|\index{outputformat?\texttt{outputformat}}\label{Doutputformat}:
+$$
+\begin{verbatim}
+outputformat := "svg";
+\end{verbatim}
+$$
+Other values make MetaPost fall back to PostScript output. Variable
+\verb|outputformat| is case-sensitive, so assigning it the string
+\verb|"SVG"| enables PostScript output, too. Default value of variable
+\verb|outputformat| is \verb|"eps"|.
+
+\paragraph{Bitmap output} To create bitmap output in the PNG format,
+MetaPost utilizes the Cairo\index{Cairo} \cite{lib:cairo} graphics
+library.\footnote{The Cairo library version is printed when MetaPost is
+ run with the \texttt{-version} command-line switch.} Bitmap
+conversion can be controlled from within MetaPost using three internal
+variables: \texttt{outputformatoptions}, \texttt{hppp}, and
+\texttt{vppp}.
+
+\begin{table}
+ \centering
+ \begin{tabular}{|>{\ttfamily}l|>{\ttfamily}l|l|}
+ \hline
+ \multicolumn1{|c|}{Key} & \multicolumn1{c|}{Values} & \multicolumn1{c|}{Meaning}\\\hline
+ format &
+ rgba\index{rgba?\texttt{rgba}|see{\texttt{outputformatoptions},
+ \texttt{format}}} & RGB color space\index{PNG!color space!RGBA}
+ with alpha channel\index{PNG!alpha channel}\\
+ & rgb\index{rgb?\texttt{rgb}|see{\texttt{outputformatoptions},
+ \texttt{format}}} & RGB color space\index{PNG!color space!RGB}\\
+ & graya\index{graya?\texttt{graya}|see{\texttt{outputformatoptions},
+ \texttt{format}}} & gray scale color space\index{PNG!color
+ space!gray scale with alpha} with alpha channel\index{PNG!alpha
+ channel}\\
+ & gray\index{gray?\texttt{gray}|see{\texttt{outputformatoptions},
+ \texttt{format}}} & gray scale color space\index{PNG!color
+ space!gray scale}\\
+ \hline
+ antialias &
+ none\index{none?\texttt{none}|see{\texttt{outputformatoptions},
+ \texttt{antialias}}} & no anti aliasing\index{PNG!anti
+ aliasing}\\
+ & fast\index{fast?\texttt{fast}|see{\texttt{outputformatoptions},
+ \texttt{antialias}}} & fastest anti aliasing algorithm\\
+ & good\index{good?\texttt{good}|see{\texttt{outputformatoptions},
+ \texttt{antialias}}} & better quality, but slower\\
+ & best\index{best?\texttt{best}|see{\texttt{outputformatoptions},
+ \texttt{antialias}}} & best quality, slowest\\
+ \hline
+ \end{tabular}
+ \caption{Valid keys and values in variable \texttt{outputformatoptions}.}
+ \label{tab:outputformatoptions}
+\end{table}
+
+Variable
+\texttt{outputformatoptions}\index{outputformatoptions?\texttt{outputformatoptions}}\label{Doutputformatoptions}
+is a string containing a list of \tdescr{key}\verb|=|\tdescr{value}
+pairs separated by spaces (no other spaces are allowed). Key
+\texttt{format}\index{format?\texttt{format}|see{outputformatoptions,
+ \texttt{format}}}\index{outputformatoptions?\texttt{outputformatoptions}!format?\texttt{format}}
+determines color space of the written PNG file. Key
+\texttt{antialias}\index{antialias?\texttt{antialias}|see{outputformatoptions,
+ \texttt{antialias}}}\index{outputformatoptions?\texttt{outputformatoptions}!antialias?\texttt{antialias}}
+determines what level of anti aliasing\index{anti aliasing|see{PNG, anti
+ aliasing}}\index{PNG!anti aliasing} is applied during vector graphic
+to bitmap conversion. The set of accepted values and their meanings can
+be found in table~\ref{tab:outputformatoptions}. An assignment that
+would match the compiled-in default setup would look like
+
+$$
+\begin{verbatim}
+outputformatoptions := "format=rgba antialias=fast";
+\end{verbatim}
+$$
+Keys not given in an assignment to \texttt{outputformatoptions} are
+reset to their default value. By default, this variable is empty.
+
+PNG files have a transparent background\index{background in PNG output}
+if output color space provides an alpha channel\index{alpha
+ channel|see{PNG, alpha channel}}\index{PNG!alpha channel}
+(\texttt{format}\index{outputformatoptions?\texttt{outputformatoptions}!format?\texttt{format}}
+is \texttt{rgba} or \texttt{graya}). Otherwise background becomes
+white. Color channels have a bit-depth of~8 in output. Colors not
+supported by the output format, e.g., CMYK colors, are transformed to a
+color with a similar visual impression. Here's how colors are
+transformed during bitmap conversion. Let's recall that color
+components in a MetaPost picture are in the range $[0;1]$ (see the
+discussion of color types in Section~\ref{datatypes}). Whatever input
+and output color spaces are used, all colors found in a picture are
+initially converted to RGB color space. A gray scale color with
+intensity $i$ is converted to an RGB color with all components set
+to~$i$. RGB colors are left unchanged. A CMYK color with components
+$(c,m,y,k)$ is converted to an RGB color with components $(r,g,b)$ using
+equations
+\begin{eqnarray}
+ r &=& 1 - k - c\\
+ g &=& 1 - k - m\\
+ b &=& 1 - k - y
+\end{eqnarray}
+with results clipped to the range $[0;1]$. If requested by the output
+format (\texttt{gray} or \texttt{graya}), such a color is further
+converted to a gray color with intensity
+\begin{eqnarray}
+j = 0.2126 \cdot r + 0.7152 \cdot g + 0.0722 \cdot b
+\end{eqnarray}
+
+Note, colors are exact in PNG output if input and output color spaces
+are compatible, i.e., both are RGB or gray scale or output in RGB color
+space contains only gray scale colors. Users that care about color
+conversion can apply the necessary transformations explicitly in a
+\texttt{for within~\tdescr{\mbox{picture}}}\index{for within?\texttt{for
+ within}} loop inside
+\texttt{extra\_endfig}\index{extra_endfig?\texttt{extra\_endfig}} (see
+Section~\ref{Dforwithin} and Appendix~\ref{Dxefig}). MetaPost has no
+built-in color management support. The built-in conversions are
+provided just as a convenience.
+
+Resolution of PNG output is always 72~dpi\index{dpi}\index{units!dpi}
+(dots per inch). Two internal variables
+\texttt{hppp}\index{hppp?\texttt{hppp}}\label{Dhppp} and
+\texttt{vppp}\index{vppp?\texttt{vppp}}\label{Dvppp} are used by the PNG
+backend to decide on the scale of the generated bitmap. These two
+variables have already been present in \MF\ and have been revived when
+MetaPost acquired the bitmap backend in version 1.800. But there's a
+catch: In \MF, variables \texttt{hppp} and \texttt{vppp} refer to
+horizontal and vertical scale in \emph{pixels per
+ point}\index{units!pixels per point} and values larger than~1 result
+in output of larger dimensions. In MetaPost, the meaning of both
+variables is the other way around. They refer to horizontal and
+vertical scale in \emph{points per pixel}\index{units!points per pixel}
+and values larger than~1 result in output of smaller dimensions.
+Default value for both variables is $1.0$, i.e., one MetaPost point per
+pixel.
+
+\paragraph{PostScript Dictionary}
+
+For PostScript output, MetaPost can define a dictionary of abbreviations
+of the PostScript commands, e.g., \verb|l| instead of \verb|lineto|, to
+reduce the size of output files. Setting the internal variable
+\texttt{mpprocset}\index{mpprocset?\texttt{mpprocset}}\label{Dmpprocset}
+to~1 makes MetaPost create an extended preamble setting-up the
+dictionary. Default value of variable \texttt{mpprocset} is~0, that is,
+no dictionary is used. For SVG and PNG output, variable
+\texttt{mpprocset} is not relevant.
+
+\paragraph{Version Number}
+
+The version number of the MetaPost compiler can be determined from
+within a MetaPost program via the predefined constant string
+\texttt{mpversion}\index{mpversion?\texttt{mpversion}}\label{Dmpversion}
+(since version~0.9). For instance the following code
+$$
+\begin{verbatim}
+message "mp = " & mpversion;
+\end{verbatim}
+$$
+writes
+$$
+\begin{verbatim}[commandchars=\\\{\}]
+mp = \mpversion
+\end{verbatim}
+$$
+to the console and the transcript file. Variable \texttt{mpversion} can
+be used to execute code depending on the MetaPost version like this:
+$$
+\begin{verbatim}[commandchars=\\\{\}]
+if unknown mpversion: string mpversion; mpversion := "0.000"; fi
+if scantokens(mpversion) < 1.200:
+ errmessage "MetaPost v1.200 or later required (found v" & mpversion & ")";
+else:
+ \tdescr{code}
+fi
+\end{verbatim}
+$$
+The first line is optional and only added to handle ancient MetaPost
+versions gracefully that don't even know about variable
+\textrm{mpversion} (prior to v0.9). The second test does the actual
+work.
+
+The version number is also written to output files and the transcript
+file. For PostScript output, the version number can be found in the
+\texttt{Creator}\index{Creator comment in PostScript
+ output?\texttt{Creator} comment in PostScript output|see{PostScript,
+ \texttt{Creator} comment}}\index{PostScript!Creator
+ comment?\texttt{Creator} comment} comment. SVG files contain a simple
+comment line near the beginning of the file. For PNG output, the
+version number can be found in a text chunk with keyword
+\texttt{Software}\index{Software keyword in PNG text
+ chunk?\texttt{Software} keyword in PNG text chunk|see{PNG, text
+ chunk}}\index{text chunk|see{PNG, text chunk}}\index{PNG!text
+ chunk}. The transcript\index{files!transcript} file starts with a
+banner line that identifies the version\index{version number} of the
+MetaPost compiler.
+
+\subsection{Previewing PostScript Output}
+\label{preview}
+\index{preview!PostScript}
+
+Previewing MetaPost's PostScript output is not difficult, but there are
+some catches that one should know about. This section deals with the
+following questions: How can graphics be clipped to their true bounding
+box in the PostScript viewer application? Why are my text labels
+rendered with an ugly font (or not at all) and how to avoid that? How
+can several graphics be combined into a multi-page document that can be
+previewed within one instance of the viewer application?
+
+\subsubsection{Bounding Box}
+\index{bounding box}
+\index{PostScript!bounding box}
+
+With default settings, MetaPost writes very much stripped-down
+PostScript code, containing only the bare graphics code, but no other
+ressources, like fonts etc. The PostScript code is somewhat deficient,
+because it fails to correctly identify as Encapsulated PostScript
+(EPSF\index{EPSF}) in the header. Note, Encapsulated PostScript files
+don't have an associated page size, but provide bounding box
+information, because they are meant for inclusion into other documents.
+Instead MetaPost output wrongly pretends to be full PostScript
+(PS\index{PS}), which it is not.
+
+This is just fine for including MetaPost graphics in, say, \TeX\
+documents (see Section~\ref{mpimport}), but some PostScript viewers have
+difficulties rendering those PostScript files correctly. As an example,
+because of the wrong ``PS'' header, GSview\index{GSview}---not knowing
+better---ignores bounding box information and then clips all contents to
+a (configurable) page size. Graphic elements laying outside those fixed
+page boundaries are therefore not visible, e.g., when they have negative
+coordinates.
+
+To avoid such situations, the first rule when previewing MetaPost's
+PostScript output is to put the line
+$$
+\begin{verbatim}
+prologues := 2;
+\end{verbatim}
+\index{prologues?\texttt{prologues}}
+$$
+before the first \verb|beginfig| in MetaPost input files (see the
+discussion about \texttt{prologues} in Section~\ref{Dprologues}). That
+way, MetaPost's PostScript output correctly identifies as Encapsulated
+PostScript and viewer applications should always obey the file's
+bounding box for on-screen rendering.
+
+A workaround for MetaPost's deficient default PostScript code that can
+sometimes be seen is to move the lower left corner of a figure to the
+origin as a last operation by saying
+$$
+\begin{verbatim}[commandchars=\\\{\}]
+\color{gray}currentpicture := currentpicture shifted -llcorner currentpicture;
+\end{verbatim}
+\index{currentpicture?\texttt{currentpicture}}
+\index{llcorner?\texttt{llcorner}}
+$$
+before \verb|endfig|. But this doesn't prevent from clipping on the
+right and upper page boundaries. Additionally, the line is required for
+all figures, cluttering source code, and it alters all coordinates in
+PostScript output, which might complicate debugging. Applying such a
+manual transformation is therefore not recommended (which is why the
+line is grayed out). Instead, users are advised to adjust
+\texttt{prologues} once in the preamble of the input file and enable
+clipping to the bounding box in the PostScript viewer. For
+GSview\index{GSview}, that can be done by activating \texttt{Options}
+$\rightarrow$ \texttt{EPS Clip} and optionally \texttt{Options}
+$\rightarrow$ \texttt{Show Bounding Box} for verification.
+
+\subsubsection{Text Labels}
+
+Another popular previewing issue concerns graphics that contain text
+labels. An observation MetaPost users can often make is that text
+labels in graphics are rendered with wrong fonts, wrong glyphs, and
+sometimes even not at all. The reason is that with default settings,
+again, MetaPost's PostScript output is deficient, in that it uses a
+simple, non-standard way to declare what fonts are used in a graphic.
+Setting variable \texttt{prologues} to~2, as shown in the previous
+section, makes MetaPost generate more complex PostScript code to declare
+all needed PostScript\index{PostScript!fonts} fonts and embed the
+necessary encoding information. If the PostScript viewer can provide
+the requested fonts, this might be sufficient to get text labels
+rendered correctly. If you still observe wrong or missing glyphs you
+should put the line
+$$
+\begin{verbatim}
+prologues := 3;
+\end{verbatim}
+\index{prologues?\texttt{prologues}}
+$$
+into the preamble of the input file. That way, MetaPost embeds the used
+PostScript\index{PostScript!fonts} fonts into the output file so that
+they are always available (see the discussion about \texttt{prologues}
+in Section~\ref{Dprologues}). Note, this might enlarge the size of
+output files considerably. Additionally, fonts might be embedded
+multiple times when several graphics using the same fonts are included
+into a document. For that reason, it is recommended to reset variable
+\texttt{prologues} to~0 before finally including MetaPost graphics into
+external documents.
+
+\subsubsection{Proof Sheets}
+\index{proof sheets}
+
+If you have lots of figures in a source file and need to preview many of
+them at the same time, opening every graphic in a new instance of the
+viewer application and switching between them back and forth can get
+cumbersom. An alternative is to collect all graphics generated from a
+MetaPost input file in a proof sheet, a multi-page document, that can be
+previewed and navigated in a single instance of the viewer application.
+The MetaPost distribution contains two (plain) \TeX\ scripts,
+\texttt{mproof.tex} and \texttt{mpsproof.tex}, that help with the latter
+approach.
+
+\paragraph{\texttt{mproof.tex}}
+\index{mproof.tex?\texttt{mproof.tex}}
+
+To write a proof sheet for MetaPost output, call \texttt{mproof.tex} as
+$$
+\begin{verbatim}[commandchars=\\\{\}]
+tex mproof \tdescr{MetaPost output files}
+\end{verbatim}
+$$
+Then process the resulting \texttt{.dvi}\index{dvi file?{\tt dvi}
+ file}\index{files!dvi?{\tt dvi}} file as usual. That way, there's no
+need to care about different settings of variable
+\texttt{prologues}\index{prologues?\texttt{prologues}}, since in proof
+sheets MetaPost graphics are already embedded.
+
+Note, the parameters after \texttt{mproof} are an explicit list of
+MetaPost output files, possibly generated from different input files.
+On shells that support POSIX\index{shell patterns}\index{POSIX!shell
+ patterns} shell patterns, these can be used to avoid typing a long
+list of files. As an example, for a file \texttt{fig.mp} containing
+three figures with charcodes 1, 2, and~3, the proof sheet can be
+generated by calling
+$$
+\begin{verbatim}
+tex mproof fig.?
+\end{verbatim}
+$$
+The pattern \texttt{fig.?} is automatically expanded to \texttt{fig.1
+ fig.2 fig.3} by the shell (but not necessarily in numerically
+increasing order) before \TeX\ is run. If there were an output file
+\texttt{fig.10}, using patterns \texttt{fig.??} or \texttt{fig.*} to
+cover two-digit indices would fail, since those covered the source file
+\texttt{fig.mp} as well. To avoid that, output file names have to be
+made more significant, e.g., by setting variable \texttt{outputtemplate}
+to \verb|%j-%c.mps| (see Section~\ref{Doutputtemplate}). The proof sheet
+can then be generated with
+$$
+\begin{verbatim}
+tex mproof *.mps
+\end{verbatim}
+$$
+
+\paragraph{\texttt{mpsproof.tex}}
+\index{mpsproof.tex?\texttt{mpsproof.tex}}
+
+An alternative to \texttt{mproof.tex} is the script
+\texttt{mpsproof.tex}, which is similar, but more powerful. While the
+former script only runs with \TeX\ and requires a DVI output driver to
+generate PostScript files, \texttt{mpsproof.tex} can as well be run
+through pdf\TeX\ to directly generate PDF files. Additionally, it
+provides some command-line options.
+
+With the
+\verb|\noheaders|\index{mpsproof.tex?\texttt{mpsproof.tex}!noheaders?\texttt{\textbackslash
+ noheaders}} option, file names, date stamps, and page numbers are
+omitted from the proof sheet. Use it like
+$$
+\begin{verbatim}[commandchars=\|\{\}]
+tex mpsproof \noheaders |tdescr{MetaPost output files}
+\end{verbatim}
+$$
+
+The
+\verb|\bbox|\index{mpsproof.tex?\texttt{mpsproof.tex}!bbox?\texttt{\textbackslash
+ bbox}} option can be used to generate an output file that has
+exactly the same page size as a figure's bounding box (\verb|\bbox| is
+actually an alias for the longer
+\verb|\encapsulate|\index{mpsproof.tex?\texttt{mpsproof.tex}!encapsulate?\texttt{\textbackslash
+ encapsulate}}). With this option only one figure can be processed
+at a time, e.g.,
+$$
+\begin{verbatim}
+pdftex mpsproof \bbox fig.1
+\end{verbatim}
+$$
+
+\paragraph{Alternatives} Other alternatives for previewing MetaPost
+figures, which are not part of the MetaPost distribution, are the
+mptopdf\index{mptopdf} bundle or the Perl script \ttindex{mpstoeps.pl}.
+There is also an online compiler and viewer for MetaPost code at
+\url{http://tlhiv.org/mppreview/}.
+
+\subsection{Debugging}
+\label{debug}
+
+\index{debug}
+
+MetaPost inherits from \MF\index{metafont?\MF} numerous facilities for
+interactive debugging, most of which can only be mentioned briefly here.
+Further information on error messages, debugging, and generating tracing
+information can be found in {\sl The\ \MF book} \cite{kn:c}.
+
+Suppose your input file says
+$$ \hbox{\verb|draw z1--z2;|} $$
+on line 17 without first giving known values to {\tt z1} and {\tt z2}.
+Figure~\ref{errmsg} shows what the MetaPost interpreter prints on your
+terminal when it finds the error. The actual error message is the line
+beginning with ``{\tt !}''; the next six lines give the context that
+shows exactly what input was being read when the error was found; and
+the ``{\tt ?}'' on last line is a prompt for your response. Since the
+error message talks about an undefined $x$~coordinate, this value is
+printed on the first line after the ``\verb|>>|''. In this case the
+$x$~coordinate of {\tt z1} is just the unknown variable {\tt x1}, so the
+interpreter prints the variable name {\tt x1} just as it would if it
+were told to\index{show?\texttt{show}} ``{\tt show x1}'' at this point.
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+>> x1
+! Undefined x coordinate has been replaced by 0.
+<to be read again>
+ {
+--->{
+ curl1}..{curl1}
+l.17 draw z1--
+ z2;
+?
+\end{verbatim}
+$$
+\caption{An example of an error message.}
+\label{errmsg}
+\end{figure}
+
+The context listing may seem a little confusing at first, but it really just
+gives a few lines of text showing how much of each line has been read so far.
+Each line of input is printed on two lines like this:
+\begin{eqnarray*}
+ \descr{descriptor}\ \hbox{Text read so far} \\
+ && \hbox{Text yet to be read}
+\end{eqnarray*}
+The \tdescr{descriptor} identifies the input source. It is either a
+line number like ``{\tt l.17}'' for line 17 of the current file; or it
+can be a macro name followed by ``{\tt ->}''; or it is a descriptive
+phrase in angle brackets. Thus, the meaning of the context listing in
+Figure~\ref{errmsg} is that the interpreter has just read line 17 of the
+input file up to ``\verb|--|,'' the expansion of the \verb|--| macro has
+just started, and the initial ``\verb|{|'' has been reinserted to allow
+for user input before scanning this token.
+
+Among the possible responses to a {\tt ?} prompt are the following:
+\begin{description}
+\item[x] terminates the run so that you can fix your input file and start over.
+\item[h] prints a help message followed by another {\tt ?} prompt.
+\item[\tdescr{return}] causes the interpreter to proceed as best it can.
+\item[?] prints a listing of the options available, followed by another
+ {\tt ?} prompt.
+\end{description}
+
+This interactive mode is not only entered when MetaPost finds an error
+in the code. It can be explicitly entered by the \ttindex{errmessage}
+command. The \ttindex{message}\label{Dmessage} command writes a string
+argument to a new line on the terminal. The
+\ttindex{errmessage}\label{Derrmessage} command is similar, but the
+string argument is preceded by \verb|"! "| and followed by~\verb|"."|.
+Additionally, some lines of context are appended as in MetaPost's normal
+error messages. If the user now types ``h'', the most recent
+\ttindex{errhelp}\label{Derrhelp} string will be shown (unless it was
+empty).
+
+\begin{figure}[htp]
+\begin{ctabbing}
+$\tt \descr{message command} \rightarrow errhelp \descr{string expression}$\\
+$\tt \qquad \;|\; errmessage \descr{string expression}$\\
+$\tt \qquad \;|\; message \descr{string expression}$
+\end{ctabbing}
+\caption{The syntax for message commands}
+\label{symsg}
+\end{figure}
+
+Error messages and responses to {\tt show} commands are also written
+into the transcript\index{files!transcript} file whose name is obtained
+from the name of the main input file by changing ``{\tt .mp}''\index{mp
+ file?{\tt mp} file}\index{files!mp?{\tt mp}} to ``{\tt
+ .log}''\index{log file?{\tt log} file}\index{files!log?{\tt
+ log}}. When the internal variable\index{internal
+ variables}\index{variables!internal} {\tt
+ tracingonline}\index{tracingonline?\texttt{tracingonline}} is at its
+default value of zero, some {\tt show} commands print their results in
+full detail only in the transcript file.
+
+Only one type of {\tt show}\index{show?\texttt{show}} command has been
+discussed so far: {\tt show} followed by a comma-separated list of
+expressions prints symbolic representations of the expressions.
+
+The {\tt showtoken}\index{showtoken?\texttt{showtoken}}\label{Dshtok}
+command can be used to show the
+parameters and replacement text of a macro. It takes a comma-separated list of
+tokens and identifies each one. If the token is a primitive as in
+``\verb|showtoken +|'' it is just identified as being itself:
+$$ \hbox{\verb|> +=+|} $$
+Applying {\tt showtoken} to a variable or a {\tt vardef} macro yields
+$$ \hbox{\tt > } \descr{token}\hbox{\tt =variable} $$
+
+To get more information about a variable, use
+{\tt showvariable}\index{showvariable?\texttt{showvariable}}\label{Dshvar}
+instead of {\tt showtoken}. The
+argument to {\tt showvariable} is a comma-separated list of symbolic tokens
+and the result is a description of all the variables whose names begin with
+one of the listed tokens. This even works for {\tt vardef} macros. For
+example, {\tt showvariable z} yields
+$$ \hbox{\verb|z@#=macro:->begingroup(x(SUFFIX2),y(SUFFIX2))endgroup|} $$
+
+There is also a {\tt
+showdependencies}\index{showdependencies?\texttt{showdependencies}}\label{Dshdep}
+command that takes no arguments and prints a list of all {\em dependent}
+variables and how the linear equations given so far make them depend on
+other variables. Thus after
+$$ \hbox{\tt z2-z1=(5,10); z1+z2=(a,b);} $$
+{\tt showdependencies} prints what is shown in Figure~\ref{shdep}. This could
+be useful in answering a question like ``What does it mean
+`{\tt !\ Undefined x coordinate}?' I thought the equations given so far would
+determine {\tt x1}.''
+
+\begin{figure}[htp]
+$$\begin{verbatim}
+x2=0.5a+2.5
+y2=0.5b+5
+x1=0.5a-2.5
+y1=0.5b-5
+\end{verbatim}
+$$
+\caption{The result of {\tt z2-z1=(5,10); z1+z2=(a,b); showdependencies;}}
+\label{shdep}
+\end{figure}
+
+When all else fails, the predefined macro {\tt
+tracingall}\index{tracingall?\texttt{tracingall}}\label{Dtall} causes
+the interpreter to print a detailed listing of everything it is doing.
+Since the tracing information is often quite voluminous, it may be
+better to use the {\tt
+loggingall}\index{loggingall?\texttt{loggingall}}\label{Dlogall} macro
+that produces the same information but only writes it in the
+transcript\index{files!transcript} file. There is also a {\tt
+tracingnone}\index{tracingnone?\texttt{tracingnone}}\label{Dtnone} macro
+that turns off all the tracing output.
+
+Tracing output is controlled by the set of internal
+variables\index{internal variables}\index{variables!internal} summarized
+below. When any one of these variables is given a positive value, the
+corresponding form of tracing is turned on. Here is the set of tracing
+variables and what happens when each of them is positive:
+\begin{description}
+\item[{\tt tracingcapsules}]\index{tracingcapsules?\texttt{tracingcapsules}}\label{Dtcapsules}%
+shows the values of temporary quantities (capsules) when they become known.
+%
+\item[{\tt tracingchoices}]\index{tracingchoices?\texttt{tracingchoices}}\label{Dtchoices}%
+shows the B\'ezier control\index{control points} points of each new path
+when they are chosen. %
+\item[{\tt tracingcommands}]\index{tracingcommands?\texttt{tracingcommands}}\label{Dtcommands}%
+shows the commands before they are performed. A setting ${}>1$ also shows
+{\tt if}\index{if?\texttt{if}} tests and loops before they are expanded;
+a setting ${}>2$ shows algebraic operations before they are performed.
+%
+\item[{\tt tracingequations}]\index{tracingequations?\texttt{tracingequations}}\label{Dtequations}%
+shows each variable when it becomes known.
+%
+\item[{\tt tracinglostchars}]\index{tracinglostchars?\texttt{tracinglostchars}}\label{Dtlostchars}%
+warns about characters omitted from a picture because they are not in the font
+being used to typeset labels.
+%
+\item[{\tt tracingmacros}]\index{tracingmacros?\texttt{tracingmacros}}\label{Dtmacros}%
+shows macros before they are expanded.
+%
+\item[{\tt tracingoutput}]\index{tracingoutput?\texttt{tracingoutput}}\label{Dtoutput}%
+shows pictures as they are being shipped out as PostScript files.
+%
+\item[{\tt tracingrestores}]\index{tracingrestores?\texttt{tracingrestores}}\label{Dtrestores}%
+shows symbols and internal variables as they are being restored at the end
+of a group.
+%
+\item[{\tt tracingspecs}]\index{tracingspecs?\texttt{tracingspecs}}\label{Dtspecs}%
+shows the outlines generated when drawing with a
+polygonal pen\index{pens!polygonal}.
+%
+\item[{\tt tracingstats}]\index{tracingstats?\texttt{tracingstats}}\label{Dtstats}
+shows in the transcript file at the end of the job how many of the
+MetaPost interpreter's limited resources were used.
+\end{description}
+
+\subsection{Importing MetaPost Graphics into External Applications}
+\label{mpimport}
+
+MetaPost is very well suited for creating graphics that are to be
+included into third-party applications, such as text documents,
+presentations or web pages, because MetaPost outputs graphics in vector
+formats, which can be scaled without quality degradation. However,
+practice shows, that vector graphics, too, are best created with a rough
+target size already in mind. Scaling a vector graphic calls for
+non-proportional scaling of certain technical parameters, such as line
+width, arrow size or fonts. Otherwise, with growing scale factors
+scalable graphics tend to change their visual character. Additionally,
+during import into a main document, they'll likely fail to match, e.g.,
+stroke width of the document. To circumvent this, it is advisable to
+apply only small post-processing scale factors to vector graphics. The
+following sections briefly discuss how to import MetaPost graphics into
+documents with selected applications.
+
+\subsubsection{\TeX\ and Friends}
+\label{teximport}
+\index{TeX?\TeX!and friends}
+
+MetaPost graphics in the PostScript\index{PostScript} format can be
+easily integrated into documents prepared with \TeX\ and friends.
+MetaPost's PostScript output is a low-featured dialect of the Postscript
+language, called \emph{purified EPS}\index{EPS!purified}, which can be
+converted into the Portable Document Format (PDF\index{PDF}) language
+on-the-fly. For that reason, external MetaPost graphics can be used on
+both routes: a) using the traditional \TeX\ engine together with an
+external PostScript output driver and b) using newer \TeX\ engines, like
+pdf\TeX\ or its successor Lua\TeX, which contain a built-in PDF output
+driver. Lua\TeX\ can additionally process embedded MetaPost code
+natively, falling back to the built-in \emph{mplib} library.
+
+Figure~\ref{fig:teximport} shows the process of including an external
+MetaPost graphic into a \TeX\ document using the PostScript route. In
+the \TeX\ source a ``magic macro'' provided by the format or an external
+package is used for including a graphic file. During the typesetting
+stage, the macro only reads bounding box information off the PostScript
+file and reserves the required space on the page via an empty box. The
+file reference is passed-on to the output driver and only then, finally,
+the file is embedded into the document. The freely available program
+\ttindex{dvips} is used as an output driver in this
+example.\footnote{The C source for \ttt{dvips} comes with the web2c
+ \TeX\ distribution. Similar programs are available from other
+ sources.} The next paragraphs give more detailed information on some
+popular combinations of \TeX\ formats and engines.
+
+\begin{figure}
+$$ \includegraphics{mpman-charts-1.mps} $$
+\caption{A diagram of the processing for a \TeX\ document embedding
+ MetaPost figures}
+\label{fig:teximport}
+\end{figure}
+
+\paragraph{Plain \TeX\ Format}
+\label{plaintexformat}
+\index{TeX?\TeX!format, plain!importing MetaPost files}
+
+For users of the Plain \TeX\ format and the traditional \TeX\
+engine\index{TeX?\TeX!engine} with Device Independend output
+(DVI\index{dvi file?{\tt dvi} file}) the
+\ttt{epsf}\index{epsf.tex?\texttt{epsf.tex}} package provides the
+``magic macro''
+$$ \verb|\epsfbox{|\descr{filename}\verb|}|%
+\index{epsfbox?\texttt{\string\epsfbox}} $$
+for embedding graphics, e.g., \verb|\epsfbox{fig.1}|.
+
+Users of the pdf\TeX\ engine\index{pdfTeX?pdf\TeX!engine} should refer
+to the standalone macros of the mptopdf\index{mptopdf} bundle, which can
+be found at \url{http://context.aanhet.net/mptopdf.htm}.
+
+With the Lua\TeX\ engine\index{LuaTeX?Lua\TeX!engine}, embedding
+external graphics works the same as with pdf\TeX. Additionally,
+Lua\TeX\ users can inline MetaPost code directly into Plain \TeX\
+documents. Lua\TeX\ is able to process such MetaPost code snippets,
+falling back to the built-in \emph{mplib}\index{mplib?\emph{mplib}}
+library. Note, \emph{mplib} doesn't support
+\verb|verbatimtex|\slash\verb|btex| \ldots\ \verb|etex| constructs,
+currently. Here is an example of a MetaPost graphic inlined into a
+Plain \TeX\ document. For more information, please refer to the
+Lua\TeX~\cite[chap.~4.8]{luatex:manual} and
+\ttindex{luamplib}~\cite{hagen:luamplib} documentation.
+
+$$\begin{verbatim}
+\input luamplib.sty
+\mplibcode
+beginfig(1);
+ ...
+endfig;
+\endmplibcode
+\bye
+\end{verbatim}
+$$
+
+\paragraph{\LaTeX\ Format}
+\label{latexformat}
+\index{LaTeX?\LaTeX!format!importing MetaPost files}
+\index{TeX?\TeX!engine}
+\index{pdfTeX?pdf\TeX!engine}
+
+For users of the \LaTeX\ format and the traditional \TeX\ engine with
+Device Independent output (DVI\index{dvi file?{\tt dvi} file}) the
+well-known \ttindex{graphics} (or \ttindex{graphicx}) package aids in
+external graphics inclusion. The package supports different engines,
+guessing the correct output driver automatically, and can handle several
+graphic formats. The ``magic macro'' is
+$$ \verb|\includegraphics{|\descr{filename}\verb|}|%
+\index{includegraphics?\texttt{\string\includegraphics}} $$
+
+In DVI output driver mode the \ttt{graphics} package assumes all files
+with an unknown file extension, such as \texttt{.1} etc., to be in the
+EPS\index{EPS} format. It therefore handles MetaPost files with a
+numeric default file extension correctly (see~\cite{reckdahl:epslatex}
+for more information).
+
+When using the pdf\TeX\ engine with a built-in PDF output driver, the
+situation is a bit different. Only files with file extension
+\texttt{.mps}\index{mps file?{\tt mps} file}\index{files!mps?{\tt mps}}
+are recognized as purified EPS\index{EPS!purified} and can be converted
+to PDF\index{PDF} on-the-fly. The recommended procedure for embedding
+MetaPost graphics into \LaTeX\ documents compiled with pdf\TeX\ is
+therefore to change MetaPost's output file name extension via
+\verb|outputtemplate|\index{outputtemplate?\texttt{outputtemplate}} (see
+p.~\pageref{Doutputtemplate}). In the \LaTeX\ document include the
+graphic files with full name, e.g.,
+$$\begin{verbatim}
+\includegraphics{fig-1.mps}
+\end{verbatim}
+$$
+
+Note, the latter approach works with the \ttindex{dvips} driver, too.
+Even though, again, this time \ttt{.mps} is an unknown file extension,
+triggering EPS file handling in a fall-back procedure. This property of
+the \ttt{graphics} package, which comes in handy for MetaPost files, is
+the reason many MetaPost source files start with the line
+$$\begin{verbatim}
+outputtemplate := "%j-%c.mps";
+\end{verbatim}
+$$
+
+With the Lua\TeX\ engine\index{LuaTeX?Lua\TeX!engine}, embedding
+external graphics works the same as with pdf\TeX. Additionally,
+Lua\TeX\ users can inline MetaPost code directly into La\TeX\ documents.
+Lua\TeX\ is able to process such MetaPost code snippets, falling back to
+the built-in \emph{mplib}\index{mplib?\emph{mplib}} library. Note,
+\emph{mplib} doesn't support \verb|verbatimtex|\slash\verb|btex| \ldots\
+\verb|etex| constructs, currently. Here is an example of a MetaPost
+graphic inlined into a \LaTeX\ document. For more information, please
+refer to the Lua\TeX~\cite[chap.~4.8]{luatex:manual} and
+\ttindex{luamplib}~\cite{hagen:luamplib} documentation.
+$$\begin{verbatim}
+\documentclass{article}
+\usepackage{luamplib}
+\begin{document}
+\begin{mplibcode}
+beginfig(1);
+ ...
+endfig;
+\end{mplibcode}
+\end{document}
+\end{verbatim}
+$$
+
+\paragraph{Con\TeX t Format}
+\label{contextformat}
+\index{ConTeXt?Con\TeX t!format!importing MetaPost files}
+
+In Con\TeX t\index{ConTeXt?Con\TeX t} graphics support is integrated in
+the kernel, covering advanced features like shading, transparency, color
+spaces or image inclusion. The ``magic macro'' for embedding external
+graphics is
+$$ \verb|\externalfigure[|\descr{filename}\verb|]|%
+\index{externalfigure?\texttt{\string\externalfigure}} $$
+%
+The macro can handle numbered files as well as files with the \ttt{mps}
+suffix.
+
+Alternatively, Con\TeX t users can inline MetaPost code in the document
+source, which allows for more natural interfacing with document
+properties, font support, and automatic processing~\cite{hagen:metafun}.
+Here is an example of a MetaPost graphic inlined into a Con\TeX t
+document.
+$$\begin{verbatim}[commandchars=|\[\]]
+\starttext
+\startuseMPgraphic{|tdescr[name]}
+ ...
+\stopuseMPgraphic
+\useMPgraphic{|tdescr[name]}
+\stoptext
+\end{verbatim}
+$$
+
+Con\TeX t MkIV, being based on the Lua\TeX\ engine, provides a much
+tighter integration of MetaPost than older versions, since it can
+fall-back to the built-in \emph{mplib}\index{mplib?\emph{mplib}}
+library.
+
+\subsubsection{Troff}
+\label{troffimport}
+\index{troff!importing MetaPost files}
+
+It is also possible to include MetaPost output in a GNU
+troff\index{troff} document. The procedure is similar to
+Figure~\ref{fig:teximport}: the \ttindex{grops} output processor
+includes PostScript files when they are requested via troff's
+\ttt{\string\X}\index{X?\texttt{\string\X}} command. The
+\ttt{-mpspic}\index{mpspic?\texttt{-mpspic}} macro package provides a
+command \verb|.PSPIC|\index{PSPIC?\texttt{.PSPIC}}, which does just that
+when including an encapsulated PostScript file in the source code. For
+instance, the troff command
+$$ \hbox{\verb|.PSPIC fig.1|} $$
+includes \ttt{fig.1}, using the natural height and width of the
+image as given in the file's bounding box.
+
+\subsubsection{Web Applications}
+\label{webimport}
+
+An SVG\index{svg file?{\tt svg} file}\index{files!svg?{\tt svg}} file
+\texttt{fig.svg} can be easily embedded into
+HTML\index{HTML}\index{files!HTML} documents with the following code
+snippet:
+$$\begin{verbatim}
+<p>
+ <object data="fig.svg" type="image/svg+xml" width="300" height="200">
+ </object>
+</p>
+\end{verbatim}
+\index{object tag?\texttt{object} tag|see{HTML, tags, \texttt{object}}}
+\index{HTML!tags!object?\texttt{object}}
+$$
+The code is similar for PNG\index{png file?{\tt png}
+ file}\index{files!png?{\tt png}} files:
+$$\begin{verbatim}
+<p>
+ <img src="fig.png" alt="A picture.">
+</p>
+\end{verbatim}
+\index{img tag?\texttt{img} tag|see{HTML, tags, \texttt{img}}}
+\index{HTML!tags!img?\texttt{img}}
+$$
+The \texttt{width} and \texttt{height} attributes used above allow for
+scaling a graphic to an arbitrary size. More information about HTML
+tags and attributes can be found in an HTML reference.
+
+SVG and PNG files can also be imported by various interactive graphics
+editing programs, for example GIMP\index{GIMP} or
+Inkscape\index{Inkscape}. See Section~\ref{Dprologues} for information
+on font handling in SVG graphics.
+
+
+\section*{Acknowledgement}
+
+I would like to thank Don Knuth for making this work possible by
+developing \MF\ and placing it in the public domain. I am also indebted
+to him for helpful suggestions, particularly with regard to the
+treatment of included \TeX\ material.
+
+
+\appendix
+\include{mpman-app-numbersystems}
+\include{mpman-app-refman}
+\include{mpman-app-legacy}
+
+
+\bibliographystyle{plain}
+\bibliography{mpman}
+
+
+\printindex
+
+
+\end{document}
+
+% Copyright 1990 - 1995 by AT&T Bell Laboratories.
+% Updated 2006 by Taco Hoekwater, Karl Berry, and others.
+
+% Permission to use, copy, modify, and distribute this software
+% and its documentation for any purpose and without fee is hereby
+% granted, provided that the above copyright notice appear in all
+% copies and that both that the copyright notice and this
+% permission notice and warranty disclaimer appear in supporting
+% documentation, and that the names of AT&T Bell Laboratories or
+% any of its entities not be used in advertising or publicity
+% pertaining to distribution of the software without specific,
+% written prior permission.
+
+% AT&T disclaims all warranties with regard to this software,
+% including all implied warranties of merchantability and fitness.
+% In no event shall AT&T be liable for any special, indirect or
+% consequential damages or any damages whatsoever resulting from
+% loss of use, data or profits, whether in an action of contract,
+% negligence or other tortious action, arising out of or in
+% connection with the use or performance of this software.
+
+% In addition, John Hobby, the original author of MetaPost and this
+% manual, makes the following requests:
+% - I request that it remain clear that I am the author of
+% "A User's Manual for MetaPost" and "Drawing Graphs with MetaPost".
+% - I request to be consulted before significant changes are made.
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-PDF-mode: t
+%%% TeX-master: t
+%%% End:
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
diff --git a/systems/doc/metapost/source-tutorial/Makefile b/systems/doc/metapost/source-tutorial/Makefile
new file mode 100644
index 0000000000..cc493784aa
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/Makefile
@@ -0,0 +1,66 @@
+MAKE=make
+MPOST=mpost
+LTX=latex
+DVIPS=dvips
+PDFLTX=pdflatex
+BIB=bibtex
+
+SRC=mpintro.ltx
+INCL=$(wildcard *.tex)
+MYBIB=mpintro.bib
+MPMPS=annulus-1.mps annulus-2.mps annulus-3.mps circles.mps data.mps draw-1.mps draw-2.mps fill.mps label-1.mps label-2.mps paperclip.mps parabola.mps
+MP=$(patsubst %,%.mp,$(patsubst %.mps,%,$(filter-out -%,$(subst -, -,$(MPMPS)))))
+MPLOG=$(patsubst %.mp,%.log,$(MP))
+MPMPX=$(patsubst %.mp,%.mpx,$(MP))
+RASTEPS=previewer.eps
+RASTPDF=previewer.pdf
+
+BASE=$(patsubst %.ltx,%,$(SRC))
+DVI=$(BASE).dvi
+PDF=$(BASE).pdf
+PS=$(BASE).ps
+
+.PHONY: clean distclean
+
+pdf:
+ $(MAKE) $(PDF)
+
+ps:
+ $(MAKE) $(PS)
+
+all: pdf ps
+
+$(DVI): $(SRC) $(MYBIB) $(INCL) $(MPMPS) $(RASTEPS)
+ $(LTX) $<
+ $(BIB) $(BASE)
+ $(LTX) $<
+ $(LTX) $<
+
+$(PDF): $(SRC) $(MYBIB) $(INCL) $(MPMPS) $(RASTPDF)
+ $(PDFLTX) $<
+ $(BIB) $(BASE)
+ $(PDFLTX) $<
+ $(PDFLTX) $<
+
+$(PS): $(DVI)
+ $(DVIPS) -o $@ $<
+
+$(RASTEPS): $(patsubst %.eps,%.png,$(RASTEPS))
+ sam2p $< EPS: $@
+
+$(RASTPDF): $(patsubst %.pdf,%.png,$(RASTPDF))
+ sam2p $< PDF: $@
+
+%.mps: %.mp
+ $(MPOST) $<
+
+%.mps:: $(patsubst %,%.mp,$(patsubst %.pdf,%,$(filter-out -%,$(subst -, -,$(MPPDF)))))
+ $(MPOST) $(patsubst %,%.mp,$(patsubst %.pdf,%,$(filter-out -%,$(subst -, -,$@))))
+
+clean:
+ rm -f $(MPLOG) $(MPMPX) $(MPPDF) texnum.mpx
+ rm -f $(BASE).aux $(BASE).bbl $(BASE).blg $(BASE).log $(BASE).out
+
+distclean:
+ $(MAKE) clean
+ rm -f $(DVI) $(PS) $(PDF) $(MPMPS) $(RASTPDF) $(RASTEPS)
diff --git a/systems/doc/metapost/source-tutorial/abstract.tex b/systems/doc/metapost/source-tutorial/abstract.tex
new file mode 100644
index 0000000000..6f1631dc26
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/abstract.tex
@@ -0,0 +1,17 @@
+\begin{abstract}
+ Individuals that use \TeX{} (or any of its derivatives) to typeset
+ their documents generally take extra measures to ensure paramount
+ visual quality. Such documents often contain mathematical expressions
+ and graphics to accompany the text. Since \TeX{} was designed ``for
+ the creation of beautiful books\Dash and especially for books that
+ contain a lot of mathematics''~\cite{knuth:texbook}, it is clear that
+ it is sufficient (and in fact \textit{exceptional}) at dealing with
+ mathematics and text. \TeX{} was not designed for creating graphics;
+ however, certain add-on packages can be used to create modest figures.
+ \TeX{}, however, is capable of including graphics created with other
+ utilities in a variety of formats. Because of their scalability,
+ Encapsulated PostScript (\EPS) graphics are the most common types
+ used. This paper introduces \MP{} and demonstrates the fundamentals
+ needed to generate high-quality \EPS{} graphics for inclusion into
+ \TeX-based documents.
+\end{abstract}
diff --git a/systems/doc/metapost/source-tutorial/annulus.mp b/systems/doc/metapost/source-tutorial/annulus.mp
new file mode 100644
index 0000000000..63cea69cfa
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/annulus.mp
@@ -0,0 +1,92 @@
+prologues:=3;
+
+if scantokens(mpversion) > 1.005:
+ outputtemplate :=
+else:
+ filenametemplate
+fi
+"%j-%c.mps";
+
+verbatimtex
+%&latex
+\documentclass[11pt]{article}
+\usepackage[charter]{mathdesign}
+\usepackage[T1]{fontenc}
+\renewcommand*{\ttdefault}{lmtt}
+\begin{document}
+etex
+
+% Set unit size to 54bp = 3/4in
+u:=54;
+
+path p,q;
+% Define circle of radius 3/4in
+p:=fullcircle scaled (2*u);
+% Define circle of radius 3/8in
+q:=fullcircle scaled u;
+
+beginfig(1);
+ % Fill annulus
+ fill p withcolor (3/5,4/5,1);
+ unfill q;
+
+ % Draw big circle
+ draw p;
+ % Draw small circle
+ draw q;
+endfig;
+
+beginfig(2);
+ % Fill annulus
+ fill p--reverse q--cycle withcolor (3/5,4/5,1);
+
+ % This loop draws arrows around the big circle
+ N:=12;
+ for n=1 upto N:
+ drawarrow subpath ((n-1)/N*length(p),n/N*length(p)) of p;
+ endfor;
+
+ % These 3 commands draw the "cut"
+ drawarrow (u,0)--(5*u/6,0);
+ draw (5*u/6,0)--(2*u/3,0);
+ drawarrow (u/2,0)--(2*u/3,0);
+
+ % This loop draws arrows around the small circle
+ for n=1 upto N:
+ drawarrow subpath ((n-1)/N*length(p),n/N*length(p)) of reverse q;
+ endfor;
+
+ % Label p and q
+ label.urt(btex \texttt{p} etex,(u/sqrt(2),u/sqrt(2)));
+ label.llft(btex \texttt{q} etex,(u/2/sqrt(2),u/2/sqrt(2)));
+endfig;
+
+beginfig(3);
+ % Fill annulus
+ fill p--reverse q--cycle withcolor (3/5,4/5,1);
+
+ % Draw big circle
+ draw p;
+ % Draw small circle
+ draw q;
+
+ % Above is used to determine the bbox of the annulus
+ picture h;
+ h:=currentpicture; % Store the currentpicture
+ currentpicture:=nullpicture; % Clear the currentpicture
+
+ % Create magenta background
+ fill bbox h withcolor (1,0,1);
+
+ % Fill the big circle
+ fill p withcolor (3/5,4/5,1);
+
+ % Unfill the small circle
+ unfill q;
+
+ % Draw the big circle
+ draw p;
+ % Draw the small circle
+ draw q;
+endfig;
+end
diff --git a/systems/doc/metapost/source-tutorial/arrows.tex b/systems/doc/metapost/source-tutorial/arrows.tex
new file mode 100644
index 0000000000..2fcf6a8e8d
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/arrows.tex
@@ -0,0 +1,34 @@
+\subsection{Arrow commands}
+
+When drawing simple graphs and other illustrations, the use of arrows is
+often essential. There are two arrow commands in \MP{} for
+accommodating this need\Dash |drawarrow| and |drawdblarrow|. Both of
+these commands require a path argument. For example,
+
+\begin{lstlisting}[style=MP]
+drawarrow (0,0)--(72,72);
+\end{lstlisting}
+draws an arrow beginning at |(0,0)| and ending at |(72,72)| along the
+line segment connecting these points.
+
+The path argument of both |drawarrow| and |drawdblarrow| need not be
+line segmented paths\Dash they may be any \MP{} path. The only
+difference between |drawarrow| and |drawdblarrow| is that |drawarrow|
+places an arrow head at the end of the path and |drawdblarrow| places an
+arrow head at the beginning and the end of the path. As an example, to
+draw the curved path in \autoref{fig:draw1} with an arrow head at the
+end of the path (i.e., at |z3|), the following command can be used
+
+\begin{lstlisting}[style=MP]
+drawarrow z1{right}..z2{dir 45}..{up}z3;
+\end{lstlisting}
+and is illustrated in \autoref{fig:draw2}.
+
+\begin{figure}
+ \begin{withattachment}{draw.mp}
+ \centering
+ \includegraphics{draw-2.mps}
+ \end{withattachment}
+ \caption{Using \texttt{drawarrow} along a path}
+ \label{fig:draw2}
+\end{figure}
diff --git a/systems/doc/metapost/source-tutorial/biblio.tex b/systems/doc/metapost/source-tutorial/biblio.tex
new file mode 100644
index 0000000000..f158bfccaf
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/biblio.tex
@@ -0,0 +1,3 @@
+% \newpage
+\bibliographystyle{plain}
+\bibliography{mpintro}
diff --git a/systems/doc/metapost/source-tutorial/circles.mp b/systems/doc/metapost/source-tutorial/circles.mp
new file mode 100644
index 0000000000..ef7eadc765
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/circles.mp
@@ -0,0 +1,22 @@
+if scantokens(mpversion) > 1.005:
+ outputtemplate :=
+else:
+ filenametemplate
+fi
+"%j.mps";
+
+beginfig(0);
+ % Use 8 circles
+ N:=8;
+
+ % Compute the "correct" radius
+ r:=54*sind(180/N)/(1+sind(180/N));
+
+ % Define one of the cirlces
+ path p;
+ p:=fullcircle scaled (2*r);
+
+ % Draw all 8 circles
+ for n=0 upto N-1: draw p shifted (r/sind(180/N),0) rotated (360/N*n); endfor;
+endfig;
+end
diff --git a/systems/doc/metapost/source-tutorial/commands.tex b/systems/doc/metapost/source-tutorial/commands.tex
new file mode 100644
index 0000000000..b3d4d16af3
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/commands.tex
@@ -0,0 +1,13 @@
+\section{Common commands}
+\label{sec:commoncmds}
+
+The \MP{} manual~\cite{hobby:user} lists 26 built-in commands along with
+23 function-like macros for which pictures can be drawn and manipulated
+using \MP. We will not discuss each of these commands here; however, we
+will focus on several of the most common commands and provide examples
+of their usage.
+
+\input{draw}
+\input{fill}
+\input{arrows}
+\input{label}
diff --git a/systems/doc/metapost/source-tutorial/compilation.tex b/systems/doc/metapost/source-tutorial/compilation.tex
new file mode 100644
index 0000000000..df6a389c1a
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/compilation.tex
@@ -0,0 +1,56 @@
+\begin{figure*}[tp]
+ \centering
+ \includegraphics[width=\textwidth]{previewer}
+ \caption{\MP{} Previewer}
+ \label{fig:previewer}
+\end{figure*}
+
+\section{\MP{} compilation}
+\label{sec:mpcompilation}
+
+A typical \MP{} source file consists of one or more figures.
+Compilation of the source file generates an \EPS{} graphic for each
+figure. These \EPS{} graphics are self-contained (i.e., the fonts used
+in labels are embedded into the graphic) provided that |prologues:=3| is
+declared.
+
+If \File{foo.mp} is a typical \MP{} source file, then its contents are
+likely of the following form:
+
+\begin{lstlisting}[style=MP]
+prologues:=3;
+outputtemplate:="%j-%c.mps";
+beginfig(1);
+ |\normalfont\textit{draw commands}|
+endfig;
+beginfig(2);
+ |\normalfont\textit{draw commands}|
+endfig;
+|\dots|
+beginfig(|\normalfont$n$|);
+ |\normalfont\textit{draw commands}|
+endfig;
+end
+\end{lstlisting}
+
+Executing
+
+\begin{lstlisting}[style=text]
+mpost foo.mp
+\end{lstlisting}
+yields the following output:
+
+\begin{lstlisting}[style=text]
+This is MetaPost, Version |\normalfont$\langle$\textit{version}$\rangle$|
+(foo.mp [1] [2] |\normalfont\ldots| [|\normalfont$n$|] )
+|\normalfont$n$| output files written: foo-1.mps .. foo-|\normalfont$n$|.mps
+Transcript written on foo.log.
+\end{lstlisting}
+
+For users who just want to ``get started'' using \MP{}, a \MP{}
+previewer is available at \url{http://www.tlhiv.org/mppreview}. This
+previewer (illustrated in \autoref{fig:previewer}) is simply a graphical
+interface to \MP{} itself. It generates a single graphic with the
+option to save the output in \EPS{}, \PDF{}, and \SVG{} formats. Users
+may also choose to save the source code and can view the compilation log
+to assist in debugging.
diff --git a/systems/doc/metapost/source-tutorial/conclusion.tex b/systems/doc/metapost/source-tutorial/conclusion.tex
new file mode 100644
index 0000000000..4caa87bcc7
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/conclusion.tex
@@ -0,0 +1,13 @@
+\section{Conclusion}
+\label{sec:conclusion}
+
+\MP{} is an elegant programming language, and it produces beautiful
+graphics. The graphics are vectorial and thus can be scaled to any
+resolution without degradation. There are many advanced topics that are
+not discussed in this article (e.g., loops, flow control, subpaths,
+intersections, etc.), and the \MP{} manual~\cite{hobby:user} is an
+excellent resource for these advanced topics. However, the \MP{} manual
+may seem daunting for beginners. There are many websites containing
+\MP{} examples, and several of these are referenced at
+\url{http://www.tug.org/metapost}. Finally, we mention that Knuth uses
+nothing but \MP{} for his diagrams.
diff --git a/systems/doc/metapost/source-tutorial/data.d b/systems/doc/metapost/source-tutorial/data.d
new file mode 100644
index 0000000000..f7313d919f
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/data.d
@@ -0,0 +1,6 @@
+0.0 0.0
+0.2 0.447214
+0.4 0.632456
+0.6 0.774597
+0.8 0.894427
+1.0 1.0
diff --git a/systems/doc/metapost/source-tutorial/data.mp b/systems/doc/metapost/source-tutorial/data.mp
new file mode 100644
index 0000000000..f6f0a1feb9
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/data.mp
@@ -0,0 +1,26 @@
+prologues:=3;
+
+if scantokens(mpversion) > 1.005:
+ outputtemplate :=
+else:
+ filenametemplate
+fi
+"%j.mps";
+
+verbatimtex
+%&latex
+\documentclass[11pt]{article}
+\usepackage[charter]{mathdesign}
+\usepackage[T1]{fontenc}
+\renewcommand*{\ttdefault}{lmtt}
+\begin{document}
+etex
+
+input graph;
+Fmfont_:="bchr8r";
+beginfig(0);
+ draw begingraph(144bp,89bp);
+ gdraw "data.d";
+ endgraph;
+endfig;
+end
diff --git a/systems/doc/metapost/source-tutorial/data.tex b/systems/doc/metapost/source-tutorial/data.tex
new file mode 100644
index 0000000000..421b92bdc3
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/data.tex
@@ -0,0 +1,159 @@
+\section{Data types}
+\label{sec:datatypes}
+
+\subsection{Standard data types}
+There are ten data types in \MP{}: \textit{numeric}, \textit{pair},
+\textit{path}, \textit{transform}, \textit{rgbcolor},
+\textit{cmykcolor}, \textit{string}, \textit{boolean}, \textit{picture},
+and \textit{pen}. These data types allow users to store fragments of
+the graphics for later use. We will briefly discuss each of these data
+types and elaborate on how they are used in a typical \MP{} program.
+
+\renewcommand{\labelitemi}{$\diamond$}
+\begin{itemize}
+\item \textit{numeric}\Dash numbers
+\item \textit{pair}\Dash ordered pairs of numerics
+\item \textit{path}\Dash B\'{e}zier curves (and lines)
+\item \textit{picture}\Dash pictures
+\item \textit{transform}\Dash transformations such as shifts, rotations,
+ and slants
+\item \textit{rgbcolor} or \textit{color}\Dash triplets with each
+ component between $0$ and $1$ (red, green, and blue)
+\item \textit{cmykcolor}\Dash quadruplets with each component between
+ $0$ and $1$ (cyan, magenta, yellow, and black)
+\item \textit{string}\Dash strings of characters
+\item \textit{boolean}\Dash ``true'' or ``false'' values
+\item \textit{pen}\Dash stroke properties
+\end{itemize}
+
+Virtually all programming languages provide a way of storing and
+retrieving numerical values. This is precisely the purpose of the
+\textit{numeric} data type in \MP. Since graphics drawn with \MP{} are
+simply two dimensional pictures, it is clear that an ordered pair is
+needed to identify each point in the picture. The \textit{pair} data
+type provides this functionality. Each point in the plane consists of
+an $x$ (i.e., abscissa) part and a $y$ (i.e., ordinate) part. \MP{}
+uses the standard syntax for defining points in the plane, e.g., $(x,y)$
+where both $x$ and~$y$ are numeric data typed variables.
+
+In order to store paths between points, the \textit{path} data type is
+used. All paths in \MP{} are represented as cubic B\'{e}zier curves.
+Cubic B\'{e}zier curves are simply parametric splines of the form
+$(x(t),y(t))$ where both $x(t)$ and $y(t)$ are piecewise cubic
+polynomials of a common parameter $t$. Since B\'{e}zier curves are
+splines, they pairwise interpolate the points. Furthermore, cubic
+B\'{e}zier curves are diverse enough to provide a ``smooth'' path
+between all of the points for which it interpolates. \MP{} provides
+several methods for affecting the B\'{e}zier curve between a list of
+points. For example, piecewise linear paths (i.e., linear splines) can
+be drawn between a list of points since all linear polynomials are also
+cubic polynomials. Furthermore, if a specific direction for the path is
+desired at a given point, this constraint can be forced on the
+B\'{e}zier curve.
+
+The \textit{picture} data type is used to store an entire picture for
+later use. For example, in order to create animations, usually there
+are objects that remain the same throughout each frame of the animation.
+So that these objects do not have to be manually drawn for each frame, a
+convenient method for redrawing them is to store them into a picture
+variable for later use.
+
+When constructing pairs, paths, or pictures in \MP{}, it is often
+convenient to apply affine transformations to these objects. As
+mentioned above, \autoref{fig:circles} can be constructed by rotating
+the same circle several times before drawing it. \MP{} provides
+built-in affine transformations as ``building blocks'' from which other
+transformations can be constructed. These include shifts, rotations,
+horizontal and vertical scalings, and slantings.
+
+For creating colored graphics, \MP{} provides two data types:
+\textit{rgbcolor} and \textit{cmykcolor}. These data types correspond
+to the two supported color models \RGB{} and \CMYK. While using the
+\RGB{} color model, fractions of the primary colors
+\textit{red}~\showcol{red}, \textit{green}~\showcol{green}, and
+\textit{blue}~\showcol{blue} are ``additively mixed''. Similarly, in
+the \CMYK{} color model, the primary colors
+\textit{cyan}~\showcol{cyan}, \textit{magenta}~\showcol{magenta},
+\textit{yellow}~\showcol{yellow}, and \textit{black}~\showcol{black} are
+``subtractively mixed.'' The former model is suitable for on-screen
+viewing whereas the latter model is preferred in high-quality print.
+Both color types are ordered tuples, $(c_1,c_2,c_3)$ and
+$(c_1,c_2,c_3,c_4)$, with components~$c_i$ being \textit{numeric}s
+between $0$ and $1$. For example, in the \RGB{} color model, a light
+orange tone can be referred to as |(1,.6,0)|~\showcol[rgb]{1,.6,0},
+whereas in the \CMYK{} color model |(0,.6,1,0)|~\showcol[cmyk]{0,.6,1,0}
+corresponds to a clearly different orange tone. If a particular color
+is to be used several times throughout a figure, it is natural to store
+this color into a variable of type \textit{rgbcolor} or
+\textit{cmykcolor}.
+
+The data type \textit{color} is a convenient synonym for
+\textit{rgbcolor}. Additionally, there are five built-in \RGB{} colors
+in \MP{}: |black|, |white|, |red|, |green|, and |blue|. So, the
+expression |.4(red+blue)| refers to a dark violet~\showcol[rgb]{.4,0,.4}
+in the \RGB{} color model and in the example above |(1,.6,0)| could be
+replaced by |red+.6green|.
+
+The most common application of \textit{string} data types is reusing a
+particular string that is typeset (or labeled). The \textit{boolean}
+data type is the same as in other programming languages and is primarily
+used in conditional statements for testing. Finally, the \textit{pen}
+data type is used to affect the actual stroke paths. The default unit
+of measurement in \MP{} is $1\,\mathrm{bp}=1/72\mathrm{\ in}$, and the
+default thickness of all stroked paths is $0.5\,\mathrm{bp}$. An
+example for using the \textit{pen} data type may include changing the
+thickness of several stroked paths. This new pen can be stored and then
+referenced for drawing each of the paths.
+
+The following code declares a variable of type \textit{numeric}, one of
+type \textit{pair}, and two \textit{string} variables:
+
+\begin{lstlisting}[style=MP]
+numeric idx;
+pair v;
+string s, name;
+\end{lstlisting}
+
+Note, variables of type \textit{numeric} need not necessarily be
+declared. A formerly undeclared variable is automatically assumed to be
+\textit{numeric} at first use.
+
+
+\subsection{Arrays}
+Just like many other programming languages MetaPost provides a way to
+access variables by index. After the following variable declaration
+
+\begin{lstlisting}[style=MP]
+pair a[];
+\end{lstlisting}
+it is possible to store points in the ``array''~|a| with numeric values
+as index. The console output of
+
+\begin{lstlisting}[style=MP]
+a[1] := (0,1);
+a[2] := (0,5);
+a[3] := (10,20);
+show a[1];
+show a1;
+j := 2;
+show a[j] + a[j+1];
+\end{lstlisting}
+is
+
+\begin{lstlisting}[style=text]
+>> (0,1)
+>> (0,1)
+>> (10,25)
+\end{lstlisting}
+
+Notice, the point stored at array index~1 can be referred to as~|a[1]|
+as well as just~|a1|, omitting the brackets. The latter
+convenient---and often practised---notation works as long as the index
+is a plain numeric value. If the index is a numeric \emph{variable} or
+an expression, however, the brackets have to be present, since, e.g.,
+|aj| would clearly refer to an unrelated variable of that name instead
+of index~|j| of variable~|a|.
+
+Aside, MetaPost, as a macro language, doesn't really provide true arrays.
+However, from a user's perspective, the MetaPost way of indexing
+variables perfectly looks like an array.
diff --git a/systems/doc/metapost/source-tutorial/draw.mp b/systems/doc/metapost/source-tutorial/draw.mp
new file mode 100644
index 0000000000..8b3affb5d9
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/draw.mp
@@ -0,0 +1,44 @@
+prologues:=3;
+
+if scantokens(mpversion) > 1.005:
+ outputtemplate :=
+else:
+ filenametemplate
+fi
+"%j-%c.mps";
+
+verbatimtex
+%&latex
+\documentclass[11pt]{article}
+\usepackage[charter]{mathdesign}
+\usepackage[T1]{fontenc}
+\renewcommand*{\ttdefault}{lmtt}
+\begin{document}
+etex
+
+% Set unit size to 72bp = 1in
+u:=72;
+
+beginfig(1);
+ % Draw line segmented path
+ draw (0,0)--(3*u/4,u/4)--(u,u) dashed evenly scaled 0.6;
+
+ % Draw curved path
+ draw (0,0){right}..{dir 45}(3*u/4,u/4){dir 45}..{up}(u,u);
+
+ % Label the 3 points
+ label.bot(btex \texttt{z1} etex,(0,0));
+ label.lrt(btex \texttt{z2} etex,(3*u/4,u/4));
+ label.rt(btex \texttt{z3} etex,(u,u));
+endfig;
+
+beginfig(2);
+ % Draw arrow around curved path
+ drawarrow (0,0){right}..{dir 45}(3*u/4,u/4){dir 45}..{up}(u,u);
+
+ % Label the 3 points
+ label.bot(btex \texttt{z1} etex,(0,0));
+ label.lrt(btex \texttt{z2} etex,(3*u/4,u/4));
+ label.rt(btex \texttt{z3} etex,(u,u));
+endfig;
+end
diff --git a/systems/doc/metapost/source-tutorial/draw.tex b/systems/doc/metapost/source-tutorial/draw.tex
new file mode 100644
index 0000000000..9ed9b3c1ed
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/draw.tex
@@ -0,0 +1,46 @@
+\subsection{The \texttt{draw} command}
+
+The most common command in \MP{} is the |draw| command. This command is
+used to draw paths or pictures. In order to draw a path from
+|z1:=(0,0)| to |z2:=(54,18)| to |z3:=(72,72)|, we should first decide
+how we want the path to look. For example, if we want these points to
+simply be connected by line segments, then we use
+
+\begin{lstlisting}[style=MP]
+draw z1--z2--z3;
+\end{lstlisting}
+
+However, if we want a smooth path between these points, we use
+
+\begin{lstlisting}[style=MP]
+draw z1..z2..z3;
+\end{lstlisting}
+
+In order to specify the direction of the path at the points, we use the
+|dir| operator. In \autoref{fig:draw1} we see that the smooth path is
+horizontal at |z1|, a 45\textdegree\ angle at |z2|, and vertical at
+|z3|. These constraints on the B\'{e}zier curve are imposed by
+
+\begin{lstlisting}[style=MP]
+draw z1{right}..z2{dir 45}..{up}z3;
+\end{lstlisting}
+
+\begin{figure}
+ \begin{withattachment}{draw.mp}
+ \centering
+ \includegraphics{draw-1.mps}
+ \end{withattachment}
+ \caption{\texttt{draw} examples}
+ \label{fig:draw1}
+\end{figure}
+
+Notice that |z2{dir 45}| forces the \textit{outgoing} direction at |z2|
+to be 45\textdegree. This implies an \textit{incoming} direction at
+|z2| of 45\textdegree. In order to require different incoming and
+outgoing directions, we would use
+
+\begin{lstlisting}[style=MP]
+draw z1{right}..{dir |$\theta_i$|}z2{dir |$\theta_o$|}..{up}z3;
+\end{lstlisting}
+where $\theta_i$ and $\theta_o$ are the incoming and outgoing
+directions, respectively.
diff --git a/systems/doc/metapost/source-tutorial/fill.mp b/systems/doc/metapost/source-tutorial/fill.mp
new file mode 100644
index 0000000000..d4c52c4e9e
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/fill.mp
@@ -0,0 +1,22 @@
+if scantokens(mpversion) > 1.005:
+ outputtemplate :=
+else:
+ filenametemplate
+fi
+"%j.mps";
+
+beginfig(0);
+ % Set unit size to 72bp = 1in
+ u:=72;
+
+ % Define path
+ path p;
+ p:=(0,0){right}..{dir 45}(3*u/4,u/4){dir 45}..{up}(u,u)--cycle;
+
+ % Fill the path
+ fill p withcolor red;
+
+ % Draw the path
+ draw p;
+endfig;
+end
diff --git a/systems/doc/metapost/source-tutorial/fill.tex b/systems/doc/metapost/source-tutorial/fill.tex
new file mode 100644
index 0000000000..13fd41557a
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/fill.tex
@@ -0,0 +1,108 @@
+\subsection{The \texttt{fill} command}
+
+Another common command in \MP{} is the |fill| command. This is used to
+fill closed paths (or cycles). In order to construct a cycle, |cycle|
+may be appended to the path declaration. For example,
+
+\begin{lstlisting}[style=MP]
+path p;
+p := z1{right}..z2{dir 45}..{up}z3--cycle;
+fill p withcolor red;
+draw p;
+\end{lstlisting}
+produces \autoref{fig:fill}. Notice that |p| is essentially the same
+curved path as in \autoref{fig:draw1} with the additional piece that
+connects |z3| back to |z1| with a line segment using |--cycle|.
+
+\begin{figure}
+ \begin{withattachment}{fill.mp}
+ \centering
+ \includegraphics{fill.mps}
+ \end{withattachment}
+ \caption{\texttt{fill} example}
+ \label{fig:fill}
+\end{figure}
+
+Just as it is necessary to fill closed paths, it may also be necessary
+to \textit{unfill} closed paths. For example, the annulus in
+\autoref{fig:annulus1} can be constructed by
+
+\begin{lstlisting}[style=MP]
+color bbblue;
+bbblue := (3/5,4/5,1);
+path p,q;
+p := fullcircle scaled (2*54);
+q := fullcircle scaled (2*27);
+fill p withcolor bbblue;
+unfill q;
+draw p;
+draw q;
+\end{lstlisting}
+
+The |fullcircle| path is a built-in path that closely
+approximates a circle in \MP{} with diameter 1\,bp traversed
+counter-clockwise. This path is not exactly a circle since it is
+parameterized by a B\'{e}zier curve and not by trigonometric functions;
+however, visually it is essentially indistinguishable from an exact
+circle.
+
+\begin{figure}
+ \begin{withattachment}{annulus.mp}
+ \centering
+ \includegraphics{annulus-1.mps}
+ \end{withattachment}
+ \caption{\texttt{unfill} example}
+ \label{fig:annulus1}
+\end{figure}
+
+Notice that |p| is a |fullcircle| of radius 54\,bp (3/4\,in) and |q| is
+a |fullcircle| of radius 27\,bp (3/8\,in). The annulus is constructed
+by filling |p| with the baby blue color |bbblue| and then unfilling |q|.
+The |unfill| command above is equivalent to
+
+\begin{lstlisting}[style=MP]
+fill q withcolor background;
+\end{lstlisting}
+where |background| is a built-in color which is |white| by default.
+
+Often the |unfill| command appears to be the natural method for
+constructing figures like \autoref{fig:annulus1}. However, the |fill|
+and |unfill| commands in \autoref{fig:annulus1} can be replaced by
+
+\begin{lstlisting}[style=MP]
+fill p--reverse q--cycle withcolor bbblue;
+\end{lstlisting}
+
+\begin{figure}
+ \begin{withattachment}{annulus.mp}
+ \centering
+ \includegraphics{annulus-2.mps}
+ \end{withattachment}
+ \caption{Avoiding an \texttt{unfill}}
+ \label{fig:annulus2}
+\end{figure}
+
+The path |p--reverse q--cycle| travels around |p| in a counter-clockwise
+directions (since this is the direction that |p| traverses) followed by
+a line segment to connect to |q|. It then traverses clockwise around
+|q| (using the |reverse| operator) and finally returns to the starting
+point along a line segment using |--cycle|. This path is illustrated in
+\autoref{fig:annulus2}. One reason for using this method to construct
+the annulus as opposed to the |unfill| command is to ensure
+\textit{proper transparency} when placing the figure in an external
+document with a non-white background. If the former method is used and
+the annulus is placed on a non-white background, say magenta, then the
+result is \autoref{fig:annulus3}.
+
+\begin{figure}
+ \begin{withattachment}{annulus.mp}
+ \centering
+ \includegraphics{annulus-3.mps}
+ \end{withattachment}
+ \caption{Improper transparency using \texttt{unfill}}
+ \label{fig:annulus3}
+\end{figure}
+
+It may be desired to have the interior of |q| be magenta instead of
+|white|. This could be accomplished by redefining |background|;
+however, the latter method described above is a much simpler solution.
diff --git a/systems/doc/metapost/source-tutorial/graph.tex b/systems/doc/metapost/source-tutorial/graph.tex
new file mode 100644
index 0000000000..b9d2e0503d
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/graph.tex
@@ -0,0 +1,52 @@
+\section{Graphing functions}
+\label{sec:graphing}
+
+Among the most common types of figures for \TeX{} users are those which
+are the graphs of functions of a single variable. Hobby recognized this
+and constructed a package to accomplish this task. It is invoked by
+
+\begin{lstlisting}[style=MP]
+input graph;
+\end{lstlisting}
+
+\MP{} has the ability to construct data (i.e., ordered pairs) for
+graphing simple functions. However, for more complicated functions, the
+data should probably be constructed using external programs such as
+\acro{MATLAB} (or Octave), Maple, Mathematica, Gnuplot, et. al.
+
+A typical data file, say \File{data.d}, to be used with the \File{graph}
+package may have contents
+
+\vspace{8pt}
+\noindent%
+\begin{tabular}[b]{@{\hspace{48pt}}l@{}}
+ \lstinputlisting[style=text, boxpos=b]{data.d}
+\end{tabular}%
+\qquad%
+\attach[subject={Graph data}]{data.d}
+\vspace{8pt}
+
+This data represents the graph of $f(x)=\sqrt{x}$ for six equally spaced
+points in $[0,1]$. To graph this data, the size of the graph must first
+be decided. Choosing a width of $144\mathrm{\ bp}$ and a height of
+$89\mathrm{\ bp}$, a minimally controlled plot (as in
+\autoref{fig:data}) of this data can be generated by
+
+\begin{lstlisting}[style=MP]
+draw begingraph(144bp,89bp);
+ gdraw "data.d";
+endgraph;
+\end{lstlisting}
+
+The \File{graph} package provides many commands used to customize
+generated graphs, and these commands are fully documented in the
+manual~\cite{hobby:graph} for the \File{graph} package.
+
+\begin{figure}
+ \begin{withattachment}{data.mp}
+ \centering
+ \includegraphics{data.mps}
+ \end{withattachment}
+ \caption{$f(x)=\sqrt{x}$ using the \texttt{graph} package}
+ \label{fig:data}
+\end{figure}
diff --git a/systems/doc/metapost/source-tutorial/inclusion.tex b/systems/doc/metapost/source-tutorial/inclusion.tex
new file mode 100644
index 0000000000..9ba1f3051b
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/inclusion.tex
@@ -0,0 +1,23 @@
+\section{Including \MP{} figures in \LaTeX}
+\label{sec:latexincl}
+
+In order to include a \MP{} figure in \LaTeX{}, the \File{graphicx}
+package is suggested. Below is an example of including a \MP{} figure
+(with name \File{foo-1.mps}) in a \LaTeX{} document.
+
+\begin{lstlisting}[style=LaTeX]
+\documentclass{article}
+\usepackage{graphicx}
+\begin{document}
+|\dots|
+\includegraphics{foo-1.mps}
+|\dots|
+\end{document}
+\end{lstlisting}
+
+Having a \File{.mps} file extension on the graphic allows the same
+graphic to be included in both \LaTeX{} and \PDF\LaTeX{} documents.
+When using \PDF\LaTeX, the EPS graphic (with file extension \File{.mps})
+is converted to \PDF{} ``on the fly'' using Hans Hagen's \File{mptopdf}.
+This conversion is necessary since \PDF\LaTeX{} performs no \PS{}
+processing.
diff --git a/systems/doc/metapost/source-tutorial/intro.tex b/systems/doc/metapost/source-tutorial/intro.tex
new file mode 100644
index 0000000000..d7e8964dd9
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/intro.tex
@@ -0,0 +1,56 @@
+\section{Introduction}
+\label{sec:introduction}
+
+To accompany \TeX{}, Knuth developed \MF{} as a method of ``creating
+entire families of fonts from a set of dimensional parameters and
+outline descriptions''~\cite{beebe:mf}. Approximately ten years later,
+John Hobby began work on \MP{}\Dash ``a powerful graphics language based
+on Knuth's \MF, but with PostScript output and facilities for including
+typeset text''~\cite{hobby:user}. Although several packages (e.g.,
+\PiC\TeX, \Xy-pic, and the native \LaTeX{} picture environment to name a
+few) are available for creating graphics within \TeX-based documents,
+they all rely on \TeX{}. Since \TeX{} was designed to typeset text, it
+seems natural that an external utility should be used to generate
+graphics instead. Furthermore, in the event that the graphics require
+typeset text, then the utility should use \TeX{} for this requirement.
+This premise is exactly the philosophy of \MP.
+
+Since \MP{} is a programming language, it accommodates data structures
+and flow control, and compilation of the \MP{} source code yields \EPS{}
+graphics. These features provide an elegant method for generating
+graphics. \autoref{fig:circles} illustrates how \MP{} can be used
+programatically. The figure is generated by rotating one of the circles
+multiple times to obtain the desired \textit{circular chain}.%
+\footnote{All graphics in this tutorial (except \autoref{fig:previewer})
+ are created with \MP{}, and the source code and any required external
+ data files for each of these graphics are embedded as file attachments
+ in the electronic \PDF{} version of the article. Attachments are
+ indicated by a paper clip icon.
+
+ \vspace{-\baselineskip}
+ \noindent%
+ \raisebox{0pt}[0pt][0pt]{%
+ \makebox[0pt][r]{%
+ \notextattachfile{\paperclip}%
+ \hspace*{\marginparsep}%
+ }%
+ }%
+}
+
+\begin{figure}
+ \begin{withattachment}{circles.mp}
+ \centering
+ \includegraphics{circles.mps}
+ \end{withattachment}
+ \caption{Rotated circles}
+ \label{fig:circles}
+\end{figure}
+
+The programming language constructs of \MP{} also deliver a graceful
+mechanism for creating animations without having to manually create each
+frame of the animation. The primary advantage of \EPS{} is that it can
+be scaled to any resolution without a loss in quality. It can also be
+easily converted to raster formats, e.g.\ Portable Network Graphics
+(\PNG) and Joint Photographic Experts Group (\JPEG), et al., or other
+vector formats including Portable Document Format (\PDF) and Scalable
+Vector Graphics (\SVG), et al.
diff --git a/systems/doc/metapost/source-tutorial/label.mp b/systems/doc/metapost/source-tutorial/label.mp
new file mode 100644
index 0000000000..da0afcbf89
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/label.mp
@@ -0,0 +1,63 @@
+prologues:=3;
+
+if scantokens(mpversion) > 1.005:
+ outputtemplate :=
+else:
+ filenametemplate
+fi
+"%j-%c.mps";
+
+verbatimtex
+%&latex
+\documentclass[11pt]{article}
+\usepackage[charter]{mathdesign}
+\usepackage[T1]{fontenc}
+\renewcommand*{\ttdefault}{lmtt}
+\begin{document}
+etex
+
+% Determine the size of the default font
+w:=fontsize defaultfont;
+
+beginfig(1);
+ % Place a "point" at (0,0)
+ fill fullcircle scaled 3;
+
+ % Draw a square around the point
+ draw (-7*w/16,-7*w/16)--(7*w/16,-7*w/16)--(7*w/16,7*w/16)--(-7*w/16,7*w/16)--cycle;
+
+ % Draw vertical and horizontal lines through the point
+ draw (0,-7*w/16)--(0,7*w/16);
+ draw (-7*w/16,0)--(7*w/16,0);
+
+ % Label the 4 positions
+ label.lft(btex \texttt{lft} etex,(-w/4,0));
+ label.rt(btex \texttt{rt} etex,(w/4,0));
+ label.bot(btex \texttt{bot} etex,(0,-w/4));
+ label.top(btex \texttt{top} etex,(0,w/4));
+
+ % Manually set the bbox
+ setbounds currentpicture to (-2*w,-2*w)--(2*w,-2*w)--(2*w,2*w)--(-2*w,2*w)--cycle;
+endfig;
+
+beginfig(2);
+ % Place a "point" at (0,0)
+ fill fullcircle scaled 3;
+
+ % Draw a square around the point
+ draw (-7*w/16,-7*w/16)--(7*w/16,-7*w/16)--(7*w/16,7*w/16)--(-7*w/16,7*w/16)--cycle;
+
+ % Draw diagonals of the square through the point
+ draw (-7*w/16,-7*w/16)--(7*w/16,7*w/16);
+ draw (-7*w/16,7*w/16)--(7*w/16,-7*w/16);
+
+ % Label the 4 positions
+ label.llft(btex \texttt{llft} etex,(-w/4,-w/4));
+ label.ulft(btex \texttt{ulft} etex,(-w/4,w/4));
+ label.lrt(btex \texttt{lrt} etex,(w/4,-w/4));
+ label.urt(btex \texttt{urt} etex,(w/4,w/4));
+
+ % Manually set the bbox
+ setbounds currentpicture to (-11/4*w,-2*w)--(11/4*w,-2*w)--(11/4*w,2*w)--(-11/4*w,2*w)--cycle;
+endfig;
+end
diff --git a/systems/doc/metapost/source-tutorial/label.tex b/systems/doc/metapost/source-tutorial/label.tex
new file mode 100644
index 0000000000..6377deb6cb
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/label.tex
@@ -0,0 +1,99 @@
+\subsection{The \texttt{label} command}
+
+One of the nicest features of \MP{} is that it relies on \TeX{} (or
+\LaTeX) to typeset labels within figures. Almost all figures in
+technical documents are accompanied by labels which help clarify the
+situation for which the figure is assisting to illustrate. Such labels
+may include anything from simple typesetting as in
+Figures~\ref{fig:draw1}, \ref{fig:annulus2}, and~\ref{fig:draw2} to
+typesetting function declarations and even axes labeling.
+
+The |label| command requires two arguments\Dash a string to typeset and
+the point for which label is placed. For example, the command
+
+\begin{lstlisting}[style=MP]
+label("A", (0,0));
+\end{lstlisting}
+will place the letter ``A'' at the coordinate |(0,0)| and the box around
+this label is centered vertically and horizontally at this point.
+Simple strings like \lstinline[style=text]{"A"} require no real
+typesetting to ensure that they appear properly in the figure. However,
+many typeset strings in technical figures require the assistance of
+\TeX{} to properly display them.
+
+\begin{figure}
+ \begin{withattachment}{parabola.mp}
+ \centering
+ \includegraphics{parabola.mps}
+ \end{withattachment}
+ \caption{Labeling text}
+ \label{fig:parabola}
+\end{figure}
+
+For example, \autoref{fig:parabola} is an example where typesetting is
+preferred. That is, the axes labels and the function declaration look
+less than perfect if \TeX{} is not used. For reasons such as this,
+\MP{} provides a way to \textit{escape} to \TeX{} in order to assist in
+typesetting the labels. Therefore, instead of labeling the ``A'' as
+above,
+
+\begin{lstlisting}[style=MP]
+label(btex A etex, (0,0));
+\end{lstlisting}
+provides a much nicer technique for typesetting the label. The
+|btex ... etex| block instructs \MP{} to process everything in between
+|btex| and |etex| using \TeX. Therefore, the function declaration in
+\autoref{fig:parabola} is labeled using
+
+\begin{lstlisting}[style=MP]
+label(btex $f(x)=x^2$ etex, (a,b));
+\end{lstlisting}
+where $(a,b)$ is the point for which the label is to be centered.
+
+Since many \MP{} users prefer to typeset their labels using \LaTeX{}
+instead of plain \TeX, \MP{} provides a convenient method for
+accommodating this, done in the preamble of the \MP{} source file. The
+following code ensures that the |btex ... etex| block escapes to
+\LaTeX{} (instead of plain \TeX) for text processing.
+
+\begin{lstlisting}[style=MP]
+verbatimtex
+%&latex
+\documentclass{minimal}
+\begin{document}
+etex
+beginfig(|$n$|);
+|\quad$\langle\mbox{\normalfont\textit{draw commands}}\rangle$|
+endfig;
+end
+\end{lstlisting}
+
+Often times it is desirable to typeset labels with a justification that
+are not necessarily centered. For example, one may wish to place an
+``A'' centered horizontally about |(0,0)|, but placed above
+|(0,0)|. \MP{} provides eight suffixes to accommodate such needs. The
+suffixes |.lft|, |.rt|, |.bot|, and |.top| align the label on the left,
+right, bottom, and top, respectively, of the designated point. A hybrid
+of these four justifications provide four additional ones, namely,
+|.llft|, |.ulft|, |.lrt|, and |.urt| to align the label on the lower
+left, upper left, lower right, and upper right, respectively, of the
+designated point. For example,
+
+\begin{lstlisting}[style=MP]
+label.top(btex A etex, (0,0));
+\end{lstlisting}
+places the ``A'' directly above |(0,0)|. \autoref{fig:label}
+demonstrates each of the suffixes and their corresponding placement of
+the labels.
+
+\begin{figure}
+ \begin{withattachment}{label.mp}
+ \hfill%
+ \includegraphics{label-1.mps}%
+ \hfill%
+ \includegraphics{label-2.mps}%
+ \hfill\mbox{}%
+ \end{withattachment}
+ \caption{Label suffixes}
+ \label{fig:label}
+\end{figure}
diff --git a/systems/doc/metapost/source-tutorial/mpintro.bib b/systems/doc/metapost/source-tutorial/mpintro.bib
new file mode 100644
index 0000000000..3915cdd225
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/mpintro.bib
@@ -0,0 +1,35 @@
+@book{knuth:texbook,
+ author = {Knuth, D. E.},
+ title = {The \TeX{}book},
+ series = {Computers and Typesetting},
+ volume = {A},
+ publisher = {Addison Wesley},
+ address = {Boston},
+ year = {1986}
+}
+@misc{beebe:mf,
+ author = {Beebe, N. H. F.},
+ title = {Metafont},
+ year = {2006},
+ howpublished = {\url{http://www.math.utah.edu/~beebe/fonts/metafont.html}}
+}
+@techreport{hobby:user,
+ author = {Hobby, J. D.},
+ title = {A User's Manual for {\MP{}}},
+ series={Computing Science Technical Report},
+ number={162},
+ institution={AT\&T Bell Laboratories},
+ address={Murray Hill, New Jersey},
+ year={1992},
+ note={Also available at \url{http://www.tug.org/docs/metapost/mpman.pdf}}
+}
+@techreport{hobby:graph,
+ author = {Hobby, J. D.},
+ title = {Drawing Graphs with {\MP{}}},
+ series={Computing Science Technical Report},
+ number={164},
+ institution={AT\&T Bell Laboratories},
+ address={Murray Hill, New Jersey},
+ year={1992},
+ note={Also available at \url{http://www.tug.org/docs/metapost/mpgraph.pdf}}
+}
diff --git a/systems/doc/metapost/source-tutorial/mpintro.ltx b/systems/doc/metapost/source-tutorial/mpintro.ltx
new file mode 100644
index 0000000000..f988b0ca9e
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/mpintro.ltx
@@ -0,0 +1,182 @@
+% This document is in the public domain.
+% Originally written 2007, 2008 Troy Henderson.
+\documentclass[11pt]{article}
+\usepackage[T1]{fontenc}
+\usepackage[charter]{mathdesign}
+\renewcommand*{\ttdefault}{lmtt}
+\linespread{1.05}
+\usepackage{textcomp}
+\usepackage{mflogo}
+\usepackage{microtype}
+\usepackage{ifpdf}
+\ifpdf\microtypesetup{expansion=true}\fi
+\usepackage[margin=1.25in,letterpaper]{geometry}
+\usepackage[rgb,x11names]{xcolor}
+\usepackage{graphicx}
+\usepackage{listings}
+\lstloadlanguages{MetaPost, [LaTeX]TeX}
+\lstdefinelanguage[ext]{MetaPost}[]{MetaPost}{
+ morekeywords={verbatimtex},
+ morekeywords=[2]{blackpart, cmykcolor, colormodel, colorpart,
+ cyanpart, greypart, magentapart, rgbcolor, yellowpart},
+ morekeywords=[3]{filenametemplate, withcmykcolor, withgreyscale,
+ withoutcolor, withpostscript, withprescript, withrgbcolor},
+ morekeywords=[5]{defaultcolormodel, mpprocset, outputformat,
+ outputtemplate},
+ morekeywords=[6]{mpversion},
+ morecomment=[s][basicstyle]{\%}{&},
+ deletekeywords=[4]{z}
+}
+\lstset{
+ basicstyle=\normalfont\ttfamily,
+ columns=flexible, breaklines=true, breakatwhitespace=true,
+ escapechar=|,
+ aboveskip=8pt, belowskip=8pt,
+ frame=leftline, framerule=32pt, framesep=16pt, xleftmargin=48pt
+}
+\colorlet{mpcolor}{Chartreuse3!50!white!95!black}
+% \colorlet{testcolor}{mpcolor!90!black}
+% \extractcolorspec{testcolor}{\testcol}
+% \show\testcol
+\lstdefinestyle{MP}{
+ language=[ext]MetaPost,
+ keywordstyle=\bfseries\color{mpcolor!75!black},
+ commentstyle=\itshape,
+ rulecolor=\color{mpcolor}
+}
+\lstdefinestyle{LaTeX}{
+ language=[LaTeX]TeX, keywordstyle={}, commentstyle=\itshape,
+ rulecolor=\color{PeachPuff2}
+}
+\lstdefinestyle{text}{
+ keywordstyle={}, commentstyle={},
+ rulecolor=\color{Snow2!95!black}
+}
+\lstMakeShortInline[style=MP, keywordstyle={}, commentstyle={}]|
+\newcommand*{\File}[1]{\texttt{#1}}
+\usepackage{float}
+\floatplacement{figure}{htp}
+\floatplacement{table}{tp}
+\usepackage{hyperxmp}
+\usepackage{hyperref}
+\hypersetup{
+ pdfencoding=unicode,
+ pdfstartview=FitH,
+ pdfpagemode=UseNone,
+ colorlinks=true,
+ linkcolor=RoyalBlue3,
+ urlcolor=Chocolate4,
+ citecolor=DeepPink2
+}
+\usepackage{attachfile2}
+\attachfilesetup{
+ mimetype={text/plain}
+}
+\newcommand*{\paperclip}[1][]{\includegraphics[#1]{paperclip.mps}}
+\newcommand*{\attach}[2][]{%
+ \textattachfile[description={#2},#1]{#2}{\paperclip}%
+}
+\newlength{\attachmentraise}
+\newenvironment{withattachment}[2][0pt]
+{%
+ \setlength{\attachmentraise}{#1}%
+ \addtolength{\attachmentraise}{6pt}%
+ \makebox[0pt][l]{%
+ \raisebox{\attachmentraise}[0pt][0pt]{%
+ \makebox[32pt][c]{%
+ \attach[subject={MetaPost source file}]{#2}%
+ }%
+ }%
+ }%
+ \begin{minipage}[b]{\linewidth}%
+ }{%
+ \end{minipage}%
+}
+
+%%% Definitions copied from ltugboat.cls.
+\makeatletter
+\DeclareRobustCommand\SMC{%
+ \ifx\@currsize\normalsize\small\else
+ \ifx\@currsize\small\footnotesize\else
+ \ifx\@currsize\footnotesize\scriptsize\else
+ \ifx\@currsize\large\normalsize\else
+ \ifx\@currsize\Large\large\else
+ \ifx\@currsize\LARGE\Large\else
+ \ifx\@currsize\scriptsize\tiny\else
+ \ifx\@currsize\tiny\tiny\else
+ \ifx\@currsize\huge\LARGE\else
+ \ifx\@currsize\Huge\huge\else
+ \small\SMC@unknown@warning
+ \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi
+}
+\newcommand\SMC@unknown@warning{\TBWarning{\string\SMC: nonstandard
+ text font size command -- using \string\small}}
+\newcommand\textSMC[1]{{\SMC #1}}
+\newcommand\acro[1]{\textSMC{#1}\@}
+\def\endash{--}
+\def\emdash{\endash-}
+\def\thinskip{\hskip 0.16667em\relax}
+\def\d@sh#1#2{\unskip#1\thinskip#2\thinskip\ignorespaces}
+\def\Dash{\d@sh\nobreak\emdash}
+\def\JPEG{\acro{JPEG}}
+\def\PiC{P\kern-.05em\lower.5ex\hbox{I}\kern-.07emC\@}
+\def\PNG{\acro{PNG}}
+\def\PS{\acro{PS}}
+\def\SVG{\acro{SVG}}
+\makeatother
+
+\def\EPS{\acro{EPS}}
+\def\PDF{\acro{PDF}}
+\def\SVG{\acro{SVG}}
+\def\Xy{\leavevmode
+ \hbox{\kern-.1em X\kern-.15em\lower.4ex\hbox{Y\kern-.05em}}}
+\def\textdegree{$^\circ$}% real \textdegree is too small
+\def\RGB{\acro{RGB}}
+\def\CMYK{\acro{CMYK}}
+
+\iffalse
+% workaround for acrobat 7+8 bugs in printing
+ \let\origtextattachfile=\textattachfile
+ \renewcommand{\textattachfile}[3][]{%
+ {\notextattachfile[#1]{#3}}%
+ \origtextattachfile[#1]{#2}{#3}%
+ }
+\fi
+
+\newcommand*{\showcol}[2][named]{%
+ \begingroup%
+ \setlength{\fboxsep}{0pt}%
+ \setlength{\fboxrule}{0.2pt}%
+% \raisebox{1pt}{%
+ \fcolorbox{gray}[#1]{#2}{%
+ \makebox[1.5em]{\rule{0pt}{1.25ex}}%
+ }%
+% }%
+ \endgroup%
+}
+
+\begin{document}
+
+\hypersetup{
+ pdftitle={A Beginner's Guide to MetaPost for Creating High-Quality Graphics},
+ pdfauthor={Troy Henderson, Stephan Hennig},
+ pdfsubject={MetaPost},
+ pdfkeywords={graphics, MetaPost, TeX, LaTeX, PostScript},
+ pdfcopyright={Public Domain}
+}
+
+\title{A Beginner's Guide to \MP{}\\for Creating High-Quality Graphics}
+\author{Troy Henderson \and Stephan Hennig}
+\maketitle
+
+\input{abstract}
+\input{intro}
+\input{compilation}
+\input{data}
+\input{commands}
+\input{graph}
+\input{inclusion}
+\input{conclusion}
+\input{biblio}
+
+\end{document}
diff --git a/systems/doc/metapost/source-tutorial/paperclip.mp b/systems/doc/metapost/source-tutorial/paperclip.mp
new file mode 100644
index 0000000000..6d20f9ce3e
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/paperclip.mp
@@ -0,0 +1,25 @@
+prologues:=3;
+
+if scantokens(mpversion) > 1.005:
+ outputtemplate :=
+else:
+ filenametemplate
+fi
+"%j.mps";
+
+beginfig(0);
+ path p;
+ p := (0,3/16)
+ --(halfcircle rotated 180 scaled (1/4) shifted (1/8,-1/4))
+ --(halfcircle scaled (3/8) shifted (1/16,3/8))
+ --(halfcircle rotated 180 scaled (1/2) shifted (1/8,-1/2))
+ --(3/8,3/16);
+ draw p scaled 18 withpen pencircle scaled 1.25bp
+ withcolor (0.5985,0.7712,0.4275);
+% For the color specification cf. mpintro.ltx:
+% (0.5985, 0.7712, 0.4275) = mpcolor!90!black
+% with mpcolor being defined as
+% \colorlet{mpcolor}{Chartreuse3!50!white!95!black}
+% and Chartreuse3 = (0.4, 0.804, 0)
+endfig;
+end
diff --git a/systems/doc/metapost/source-tutorial/parabola.mp b/systems/doc/metapost/source-tutorial/parabola.mp
new file mode 100644
index 0000000000..f508df4fd7
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/parabola.mp
@@ -0,0 +1,45 @@
+prologues:=3;
+
+if scantokens(mpversion) > 1.005:
+ outputtemplate :=
+else:
+ filenametemplate
+fi
+"%j.mps";
+
+verbatimtex
+%&latex
+\documentclass[11pt]{article}
+\usepackage[charter]{mathdesign}
+\usepackage[T1]{fontenc}
+\renewcommand*{\ttdefault}{lmtt}
+\begin{document}
+etex
+
+beginfig(0);
+ % Set unit size to 108pt = 3/2in
+ u:=72;
+ v:=2*u/(1+sqrt(5));
+
+ % Determine the size of the default font
+ w:=fontsize defaultfont;
+
+ % Draw the parabola
+ draw (-u,2*v){dir -angle(1*u,4*v)}..(-u/2,v/2){dir -angle(1*u,2*v)}..(0,0){right}..(u/2,v/2){dir angle(1*u,2*v)}..(u,2*v){dir angle(1*u,4*v)} withcolor red withpen pencircle scaled 1bp;
+
+ % Label f(x)
+ label.lft(btex $f(x)=x^2$ etex,(sqrt(3)/2*u,3/2*v));
+
+ % Draw x and y axes arrows
+ drawarrow (-u,0)--(u+w/2,0);
+ drawarrow (0,0)--(0,2*v+w/2);
+
+ % Label the x and y axes
+ label.rt(btex $x$ etex,(u+w/2,0));
+ label.top(btex $y$ etex,(0,2*v+w/2));
+
+ % Pad left size to horizontally center figure
+ label.lft(btex $\phantom{x}$ etex,(-u-w/2,0));
+
+endfig;
+end
diff --git a/systems/doc/metapost/source-tutorial/previewer.eps b/systems/doc/metapost/source-tutorial/previewer.eps
new file mode 100644
index 0000000000..13407ae150
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/previewer.eps
@@ -0,0 +1,378 @@
+%!PS-Adobe-3.0 EPSF-3.0
+%%Pages: 1
+%%BoundingBox: 0 0 974 583
+%%DocumentData: Clean7Bit
+%%LanguageLevel: 2
+%%EndComments
+%%Page: 1 1
+save 9 dict begin
+{/T currentfile/ASCII85Decode filter def[/Indexed/DeviceRGB 255 T 768 string readstring pop]setcolorspace
+/F T/LZWDecode filter def
+<</ImageType 1/Width 974/Height 583/BitsPerComponent
+8/ImageMatrix[1 0 0 -1 0 583]/Decode
+[0 255]/DataSource F>> image
+ F closefile T closefile}
+%%BeginData:;
+exec
+!!*)Um/I1h#I!.df\smX!W["XI/jKZ$5"1'1-SNHI#4oM-?756EA&4c:n#Jt"q`uFlMfH%oILFU!X9
+<O[-(5nkJac7"qNE%k5,T0IUjE-gZ%_Cai8R582l.HLXu+Je"a%AQs<s%3&3'%%grXM"remD1ItkhO
+L)@(["O-b2`Wc;*utgs#!bmgH]=c"I6$!DjI;6_:/=P1*#.&Zf7eTk84Z1<YK,eqr(K4+ABX\gVFGk
+U&-b(qMD5l:'acO*ad#[G$l)^UYF79k'6pG1a085A%3T/Gb1GC_Vj`Db#m:>;-)H?('a=aL.^*/J/0
+.[%\WKE@O476jd<o+]05RuB`-c/[)PpXah:7J5e?0-1Pak2`#omg6k1RG65/*FoeC'^\'+7o_O/^.T
+cdL-mG\79n7F/haa3WD8Vk_o*d3Vb?APFGFZFma$o2d%E'K`2&L,>p7n<qr)Ld;om[&7_WCHE%37:U
+re7\nhmauiXAc,4IKEaq.q`K$";-m'&8k33C7P/=JRSABVST3.DGPI$sj$Qoih&e8MdACB?23J4mS,
+Z27i]Qm9q-;T[\+UlN)Rp:*2\Z;>d5<R`XgFX]i!!`"<JG0Zt/s0c<&JFY1Fo&eJp,PY9Q)FMlQLfr
+Xoee;mF)Ue#+nKZ=rKWK?6YH4#-1Q7.nRAm*E(BFd\,'E37Q*="a0YJ!<qom!ofn'*Y'fl_cM3-h7o
+(TI0/GLd<`@;^Xt2.T+',I]?;DXp5sI(N/U"N@+XX,7^YRGUF"eBYgYIpJb)j*Z+;kD0,pWEhr:0CJ
+kN_65YH4=fS9o[1(DmnZp@C!p0_kM=FEV`cjl5Rch;[2<ahY6EKQ@+jqUa-N][ba](D(MucEP.._P)
+At:F,Mul\!@2IriaT<h76tETben,q;cg4;Uj@,&!.>>I)QGmFpUD?fJh]T!l8TM)FkhbamSYmc1Z'H
+=)*2OnS;5C0cc`*uXY6il^Q`J,g]g3$]7K#D>EP:q1$o*=mro@So+\<\5,H7Uo<*jE<[.O@Wn[3@'n
+b-^757;Rkop>q_R=AlC^cenm@9:1mM9jS"!dTMT<$3[GQ$8#0$s<4ZX!SPQ1`C/m<k<ioGu5cYX2j`
+\=EYZP^B4!g3;B=(iZ<k:G/fl+B*DHAorf'R[o?>ioU`Obkp^gM+`4=1jRLW!S=fUQP4*KS9PE`kN$
+P8BM.Aoh+fk'&t\[,pou4XQLi7>#=I>.[gn=g,J(^d'oQ&.8`=!Ol:E<%&4^"G22J%GpZ*^>Nt5HC]
+gMSQOKbqGt*k12%,M;E:;HE&\qGmE]5>l]6h!kO_e?*hR#<&.f,kJjDTF[L9d(K`\[>2!uLb/e@:&!
+PjPmUB87=U(Rh\5e7Tr+HOA\$j/!?"Iu2?U_=3TMl[F!`!T*L%44?q*rA8Y'CM1hJET,MTRcql'rT@
+4>8Ns;PX?J3M]=r&a:YE`",$u26A6b:i'\01JLF1oK],0opnfH].KG&d:f\0^JS8=:JH7`:(eX%VqA
+>m1,%;Do@A%?O!)eKj.OJT.DB)C/.t.VTi%T45!&Cj&1X.A$;B5sMfLjnq;H0&38eRBh!5Z`!GaX>c
+/;fc\oQ6QMatfDr+!?.2@NZeXg0=\%[(9aC;ABWfQdGA!(A5a+b(Cef<U:-GLaX*nQj@@BM#dmV1(k
+!$nu<WZM$RLP,pmQoQ@arBLmTN_,'BiP$0$OP.+$On#9"o^\d<3(LaZd_>lY=tA_F&0k(3qSSOm<rY
+tAMOTb_*Hll]]Q@eq3edTpOZ?kgbM?jJq"1L8UdrEj%@]m5RsLbPcYM))SPE?ITKqBs8g8-CGMW*Q'
+O@97>!QNB]+"IKP[BX!k^3D's*Am'9&REHJV>(I&W%T%l@Bn3XD$.PG\JdT(PE0t?Q<goA5PgWkjTV
+D!b0;*q!A$"cpAXn?d2i]o-h7JF'MBIN]8-!Ct#fM:GJBQ.kTth?9:0bRE(kr*OVQ?1k=TVsG+kon#
+IGB.S&Vm77[B[n:I"E6P-0$:TR.#Ca+2@;-*3m,+&7u_p:4k.fQugto<Pfo+T66.f;@?F/+@78XfcX
+A>_AQRFBZr8a,='_M%9/iM22)']E\i>u#WO^O\?Z>)EG:BYJk\UV=9&fj3$\uo(<"DII3=TZ3/(e6T
+qH79)M(5&S?O[S6]s#1,e;tI5QpZ7CX4,a7$iZa#TX5/-6R7nnA%PW5bL3_H-\c;3C!SDM0$I4,e,P
+7j]hdn/'<K@."T1RK#(gt!dCcghEs,EC0_DR"9E*HSek!af(gt/j:U!1p9%0,P(eLdh4FZMF<*n#6r
+&8)#;nhSc]sr$%a.k]1cP&b&Tg`Z,T$jnEb>p('L=%m%"Z?!d,/%(UOoW3K#XGc)[I-HM@d.]X:P@8
+#TJ$uE#CFNJ,p[c_l[\$Q5_p<CEl[Wb^r([3X:6@fouj-K>9a?7$UCD;##;H5`m]N\NiLnciJdI.$u
+u7"IaiHHQ[n/1S<mBL'WI3G7+\F8\$lJ@/p=]Yn3891'DtN3A?fAY$a:'$>flb!tV?I&2`q_/1"-rP
+ERat`+=]L)k;tZ#]/WP=T6HJ)<#!,4lJmd?lu!39U+Te!#"PI5b(a:+L>kac!gq^',#bP1@B-MC$=s
+FbTeHUgkO,&>cJ&K@X)Dqn4,56'*(;UOB==JL]N24M6Kg\"H`fp#2ipG<)NugKgMG/Gk;U^)hWqkE`
+k5j;(7c&jc\;=^0raa9]hOA[,,d_Qb_c_g%>8p6(q-=PZ_fD(EJ*^!\gWBC^V>a"XMUn0Z`udO&]sl
+:iJTk;1d8-TdVT%2K#VGcfZ`G>%M!C==]J0bbi@"JlO%/#Ug&JA:fBXnp?)QoDlTlLX8qd"LeL7K4'
+93Q6:H]`89RZHbC@aU![QGRU%d1!N4I_opX]Z(9NgR"!g]Zenb<k]"o[3-m1bkA,tCEFW`Xd&defan
+Gj%50$bg]+@NW1^^gm_RT?rrSmB+=.-B<o;6eZS##tZlJ,uhV(N5f6_Mh;i!!Y.a28Ki2]A#N'4DO3
+Eik>kL%g50P<#3tLOE;QM67KLI-*[F`YgbqZj)CSGY6mlWTZJB90Y!,e<i$pX_DW^5^k,;f"[j4"*"
+[ocqWu*mN'<RrkhK(SUsEF*o:VbWhVLclj&1l@80A%%X?lU_bFi;AL6G.9e3+g=;Y7^X9CV;c1/,#1
+::LQ8.1In$/7\%7a2)d)kJ,I3I$Cn7E_M:^YB!`4`R2oc*QtHFG`pBD)t'+%X2kE3+JMO12U#P<'ED
+!eJf'*%.$>;VJ-/e*g/0YX@m!HX<EE3K['a+?<]-%>\-j]81>9cEWX9uI6'2ls^aM&h@3Dfl!XT?V2
+%Z#_W%c$G=XZ)UKb83K2AnP)1Rhi$G%+NPf4ZIVPh5U;hLZ>uE`0DP80,d9>fehPJe=q+$HO?K7?73
+ef7HeD=#;49Jmc)7?\;cH<5fB'6dZlD!DVB$)'Q;1p`,FS#WO^OTic:phgc*]JW^eYJqF[\3$_''9&
+2!E-,X\pK+6j#+qBV=0IZu,_FRuM@l?V!SKOYI:Qb\q1uiN*RVjUiiu$?-O(84p6i_i(QE^kFRYEJh
+C7+ueP6\&W/;6m1h64#T?l#Suj1?A9Qsk?MmkA/h`qR2A)K$piTgKc=O^<k5U4k?PO9K4Ba^57jMUa
+KS3[FVY&&_]-Fhti`$r4(9TW&?^=7aVd6kH-ARM5fJe+uef/m%.5^@o7H6+qI?f63\XS#T.0^e"/fX
+X!bb$&^%F[i9mpUmgpJ,h0]/HmHEZ%[_Ii+**A94ShktUXl>7^nG*/:6Wk.*_(d7ktfXYGQ$^fqBoV
+4lhl5sP$&k4Uo@W++=Ub%Vk3Sf:mOa>#YUgk#53m59R.m',_D@6>_'Y4,g[.`4dQ*C$#BNj&."LGir
+6Dh'7,<8C&kBf/jS%H?R00^'U:(Irnl3aLBV]<_mf:@TOYM;6=<:b5Y;?53!TTE]JBYTY"$3g1D;-8
+K"7$Y-A2Yo"jnGWQUdGAeaP@!JCGA8=HEjjKI-[BTL"Cl=:IPN\N']gi0(%2'M(&[;!r1u8"rWf@N7
+gmnKoR#e3H<Oo:0lAqBA=@OV4Bs.;[-tkK+>B&nE0JLf,ijaQT*(U#_haOa9hr3CtZ21oHTOV1ZKb<
+@_X&YEfg@=\CQ[.j_"#QP/Fd9=]<'jV5Cq'*_l=3JfI_"M^>Q-=ol]R58EEaI1LHBh^Ue2-\#GRaYk
+c9t@en9m#$WdtVj;3QX9gjL1T-V$9'8H7((^lCJX&E).A8BP1a4S^Z_L:SUuT8Ncu/'EWU-3Cc3q,m
+Pghgm_*N)*?)C![DePU/<BP7:3/$U=<dYc@Tj[B_<F=1k(K]g)N[tTgGRIC6_C03D/OU2B[N@1kSU-
+-\T$@$ApBtX0jcVktM'iidac2&iM.l*C:GAN)C7m907h.-)mVZVimJt7"m=m'EWe`M:8(]Kg;UNJtu
+BZED9O=8>-)B>-(`(\Oi]I6)\<B<Rlu&.E,fI!&Y[j<2*)gX#4C`p'"MqgBD"qb:Xp@6i_rWB\`s)k
+p=jYG7*$p;#gloTq\cNe0-fV`H:OP"JVpE;'/mffV^tJk/pJn?:dS=q\4,Zda6076u8EZZLftUOh3>
+8/Ch0BQEGVhgC8."h8Zu8BE8A-$nR;K%fe<!!#Y2,)iBK&Z8@l]c]Mfe77C]%PN5o(d;<jD<Nd'fe:
+e2(o""(*S>9,9P1m0+-u/\J]gO>u?9:h18DW7>(Qs4YX6G&72>I5.lL*Kt"(qcXhPg/7!8n76J>[P.
+_)I0FhqO?M>im*G#j(dlTOL1I2uuUi0EA/d:.oDgkp4i-:())#/gkf@!$^QQPgMo]KfqVn\.9TTj=u
+!/EM']?#9sPl2iP#8$HCRW+c4F$5&s*e,h?s-)>p%bEP9/nfe3p!1`Mi;$'HNNZiE"7!j[=W%o67o(
+L=*!?8-7b,C,1K@;l=-Yf3?X1]jW:'leS<"e3gSY<ch63MC)/G/dN-<!l!HB+\Hr_`:X_k%m=Q2!"r
+bMab)e]N?"CN0Ydb]kcZ?hbeCeG8$-GrF\h\PVd!4eiI_Ce_2%.F=+?G,a;PkH1iX=-EPg',?j@04/
+]Mtp!!uNMQMIK!/8f&\sI%VBFVCAFLHIh(3!/HiC6Hl*o#%c`fDd1+[EL8MP8e&F`,H;6A<L]'`u[Y
+&?XiQW#"dW]0=$smKG]Y-6iLMPQ51Cnc0nZ!*:+SWbY;?XfDaS\$g@6nNFL]nsgP,@]s'R]_adrGQH
+FNg3iGk3QSW0-fc4"MXl_@bP<4`YZqj3:1Tu</o_!=5R#Z!5h&JIGpgIqNq2AX_1;(]*Tk-Ai<mdP:
+q7SJkr;lBc^q'b.R)[g[G$[[WZBZ:=Id8K"/p:P?-^&miujX1Jlna>7K<LdeN=&"gY)=>aY#?O4.BD
+X.nrAl^"U.9F2DH/Dl.1)-h!8b^N*+!gZ`'_o$_oPL`0u%U2/@rKWCl2MY0rLk=D4*gMTgbkuI";h1
+H`HP?(k`=t<[X'>DLj$F+CsI=7e4?C%D:]j'NEbnfmm*eC-PH>E'l;u'chg\d\?3^\^?(Nr(HLLEbh
+oDdA=%GU/s*oKRHOf"a;KCf(<fW.4Ym@0m[$4$I`CFX:urkHAL.^.b/s7?9+!=;!W!5Ki]^bNSh49W
+H!"d"B<^gm\cKF"g[#sb9n^p3bf,R_E8VEio9^iU'_M746[1(+[]SC$'(nsD\`T`s@\$1M8PWVaM_=
+2C>+"n3O`E!cV5R)&i=_#,7ME.S\;K`f2G%B483BO?XQ?pRV`(t*a6nb[h>.%`%>Q$=pLTG*"2!!5g
+k_?+>cr%Fm;JUf-L$n4[HTalX8@"B^,"qW((3@4kg&clqP!_>K`q([Kf/dU)RL)MUt&U4G_@DaJrS<
+=tj@Mgg[.ZDS/_e_8kX?Q\5g-coI`&UIXoKX4CJV#9p!"]Au:]QDnqo'HD`@-onJ7:5Wl,+2W6!RHf
+(kJ:c*(?6d!RpCcTO%\M!>7?lL#@NuC_m'W3e3l4L&!a3Uch*'!/*>1_U&9Oi.VNZ:I[D17JHjP#a:
+2:Sd9s+J;d]k<*_tLid`EjL%s@kS8,A]Ak$ko`uHi=.@LoYG!O0_'mQgA`'([_==07da5Tu&*&IjV1
+5!*.$hQ4T$pBj&=+`cD*GMlM!+%ug!(()k)Gl,:aZkZ=]7>uJ_Dmd2d")IJ2%4kb_`:DM6raSE!(c1
+3%Od<mTL_Vhp5MA[*CqHEF;#/+D2rT!$UfKAFFQma:Pn-VQVe_/iFa%`O,2FuJ_1Tn'VC=$'7i][8D
+&V3aM%jD`;iFb$ZpNJ5feSN)&]*18l1+ti.7,gXam4Mb5!d7\LJ"ae4AQd,nt\J.&`%HZUt(gVHfff
+nf3MI&k7D78k`nf$l4aE=-cZ._.aCMbdbg>X9#gL&[[7kBYaaAXU,;H!#3A*i22ca),.-Ta'?_ZS<q
+D#*@Ei9#rI#8<..FK^VtTRV83Yagj+b7rI>Hj#"W;s=\9$Wlia]:-Ua?DR77B_Kb5lMbD;CN5\<*fK
+h^Xc:'B)QguYVBBLc=g!",6\@55s1nqLgic"-F%<)gh@CsB7p9E9SC?r/g.((CM%6=E^#A2YG=LdY]
+L32BS,(Q:gn:f%,n"<9pb?r>8V8Tk(70,^E\N"!i/:G3NG.=!4g:6GTi0P!-W!%1L`!jXLHnX';#9;
+W@N5fPhb42@Z?M,^cN*eFA?[!GF2YQ:?AkTD>qH3ZN`0j(^8;\lP=[9G4Z.u48]!\T]g5QXId2h/VN
+E*,4L(Cc/<@Uk]$<];%[aCK<o4Jj_A3A@[*THHLmNrr$%kLG1M$jsiVc>=+j.h#Yf@;"Lb0rPd7%L;
+2S>.>GnHshP<F*ZT-YA(H#>Msh`I`B]@hH-]QY(ofPeq(#[HLXJf/)Ti@HsT#a-_oeqH@9,7B=H^cp
+j@Nt5H!*BkPK^X?bbdur;XPD$j?[F:W*PA_%99T"i6::*='Fe1^s`-OK:#A_[t$L%Df9=3=j%?$q1c
+HOXs2LZ&q.K'uc;O>o1Kk'Km;QOfWC=`t?Na)95V@I36NC%#"7COrTH+aV%:4-,NMQR4$,iN27uB;C
+ndtb7`%,/\Y,i\M)/49<BqmP:Xs7bnEe$29h>$h)EUmN9*(FPH=.5cP+Oq1V@c#_`uK*!M)O'PV!>3
+d1f:i7F@?:*CnNlN?q0EPcZN1dhL%a:",?o3@?SGo`7q5F;6r;eJ1eY<Rm@O?!#SlN@.OXFVRJPb*=
+hq?.YA/I:(VB%>@O-N0S6b=V?.*@G-r`S7``%H([kF6*NBh>)%a+BA8a>I:BK?4d0m-(1"Uph%Z9K1
+`@^'#&049Te]uDJMc-q)MRuB?BN6q#&+u#6(`8WQn9=t1)CQAl+OT<abR122@YMtVQJK:O$TIg7aH-
+A)J]P0d0G2jpngc(@17T!LZL/cTnm:s%SrMF+gIaVQ_nWe1m+YK=<%HRdBIEjH79T(NOh+bU4mn2*"
+dr,@@N9O+YfElKk?-XRVS2V>/oZ;G/!J4H&g+-i`bd#:Bnh$*,B2.-EJ1!_-#D_#0)Bj:7C<qcq+\?
+=WADo;_Um\&]U-G[IKMGb/?V[nt)qo9$;K-EdY>AST9V!d-Pha@QCdeN"4=Vob;tK'a8$cWA0+#Tr'
+`#VTjd1K;3.X)?mGr)B8okQ3Yq7Pa<H/ng_M"eL^]<6BV*!inh\#?E^#\F$21`_0#Z0]g8*\;"S,_.
+X;q+O$lf+iS=]_3^jQIcX*N&`VB'?)SZ7E6hp,a&G7*'!I@OJ!^-Zak2(1[/Bf\#R:iu2aP5O#DD3m
+Q0Q?hYkeD*i/ZuP0*&#bX-3jS\1dO(ms%Fr*F=q"L^_dR^i%ppTY'LdEp`U*fU_8@)S7dT'7Pt[_+r
+Xjgp,kiG1uPpq"e^f4`)q3:TrEZu:IZ*^p_<=.HjXF8JMJAsE>RTX:Mir#)F8qU1rPT)M;qi4%=tVm
+6)7569m.qua8U/<'Ej-ZXQ:4-Wtca.;)N@E0JaPg*7j?")Gua`NC]En,XR;*&GdM65\N!KFHKia&AU
+DpZO@i'?86@qah:dg%3_NI+`'1Y86K2#jO45MTsc52nX;;Mm'0E\FD6]_V[.ojq3OaG:)E]&_GQQ$R
+71^rXjB*MT:EBDZSb7-M0a9^BR6"$;.iR),9>!-=(Ti5E_(JcX2][BKEXJFNB*mse;VtLA9;Sm3?^L
+#"PtA%*QUjj_*4b@UR]fl</DcEgh+e!TScE"9aBkf`0C^3PQC,J8cqN.r<&cdBPN@&HrIksD2hM38e
+$&ZFN/!OQrK2K;.;*/BZ2\k'P`p_6*`?'GV').C7;,q1c4%Q*>,&@gJcX"98K](VH#2Gdn5RoJES4q
+,%MEfof<G5bn$:d=\VkOF'"Drr\;_K4?tC3oW(,K4I%t1."S-o8E_B'F=O_uT[?_rGaTI-eP"JV+]=
+s^'3#[VYL,ta=tC!BYr/K_f#mbDL5^$qUJP[NHQK(SKfCOA>.rU3,@?jM!04Jt.5iPIp$3osKsn#$0
+cN6Mm#8BL<kVI0g4B;/[8jYm1=d#TB(f]_TQ3g\)-eOSFI@D"\P?0@SG+fJmR3cn17?BWH^*[RrPp'
+^p=>gNG+u*q*<i31Okoa+,-APh]ZMGd?+@?F@^HVjOLWKk-`qF7V9P&tgAJC9:O\EoIXu^gm\+D:;1
+V`1!#L[dhR,I'mm0_QQKnbale7`("B`AtDK/iR3GK^jHbQnV<o$nCM"*b:YkS+^?rSY-l!S00"[!QV
+X;cjn4qP0\ijr@,08d!X0ts$)+lEW=MX_0GT?nYH&UU^'YuW!)onsV/]O=3_aGq_0;]B5#@>#o)-5"
+g5+",iqk:l<"Yjr#5ap^S)0B8A>[P&b6f12;$V=;bBk;QsO&XDOpeHKdU'+HrXQ^)71)Jnb0LcfT_1
+&_3=H0PRc)#jTkrb^+%^/N*82e#p:B[-AD).Y9'M/n?"5<8jeL>-T!C$(4QU1dlVCHH>(MG8YbP5j=
+\[4,Z._7A5D1hB@KP2-$aJ$P8;l'i9)o<qNH<ArH]C>]'mAR!_Xp^Vnuo*6gq\Uha68F@r$@(/>K5?
+b?u%=JJ+K5TFHR_$"\]cU+\2.bR#K`:>Oe%1UKm#sb.O+LfF9)"Lc)<5.rMu"Zo1GSX]S-K_=/OdH7
+%<WQaBT@\gHbrepBYd"s6do?4+*bgT9=;,bjrGJ`(?j?]D!YnT)S*u^Y:A^*]7E>ST<1ZJ1oS('D[E
+(M;oS2OU0Q]nF2"3U.X7,T4P-;]?<_ZaI6Hh[Jn">3SsXfhqAQ,:Vh7[beQ5#_ki?i%DgC<mpm$?Nh
+0tc8(VCY6==+VcTp#bb)oq-^E.p5H\bA]Nh4>uMj1BrX0OSb,J,go-FL/f#.uU9BIE[s3VGf_gT6)A
+hbNn"&(O1]R1bkVb)L]6;Y&UY>aQPVJ;`DkpC=.r^4p0:p-PZCQc0d?:Ula(s%b))[[_6H(ppZ0sHV
+Pf/odkX<?ME2j8O8en+2UI\RC*JNFq$U,a^Cl.[=Vh`6N+(83kg@tI_D<LFWSTV?YQip`b75Si$JVW
+M8nuQ!"mOZOUomYDg&o,Gdr`(MbEco%/0[T*ra/S'2'ShNjA\>eceOA"cZu\O9X-/Us7.:bqH$#%7'
+bbRfUHk!X:(U%Q`fm/9-4tnc9[2WJ:SXFHg_Oo5068/4B]$Ge0jN"Ro5Ycr=Dur$/EH"m:[[n+-D@W
+<U_)$7S$)Nl^cFSI%fDqnbB4E1ZmpV$lIrQsm#Y&8)@UoFaWl(Tn=40VJmdgl*[k)@mr.Y8IbhL^a]
+C"cglgE8(ikr+1^o#0K.@;!`dQj<LnmQ8&1HnJJlP1]su2%<2`%d)N"[OGWKD&[=/;M'<*mFrM#?N)
+6MWbUAEHqYf`1iitE+d#(ubU1\B<'I^m2C?!h70al>7!H5-Jd8nDp>$7NP?I-k38J)=q9]j`?7S(&=
+br5Zb%2Z%p(ZgDXi(Y!7Ll(YS$IMQa#t2BX.fN4)oM7m4;4rLQUf]?bnhEcUkf"4P3q?s.'^SpalpR
+@>FH6ue*2Kn\jaIAJis(XuN'S_%@5ArZ\GE7]"7P0sn/EHHb_4Bl&[<u3.!DE1'`Vho&T<%W:ib1WE
+7<5TLCs;_JJ>%YRj*X%VWfQkEFOUl%ZAYP\g[^]Y^4Uc6AG&#<^EPpdSV,Y(l0@t$Ko):lVQ7i)'71
+op@<*Pno@bC?LfiP-`;h>i<H(@6QORT-..tR%J4(j&I39(fPlH>16tBBRT7e@*HItdi>dIPX9;t&/L
+S:H1<U'rc;g#3nhI6uB,V]IV"+Z8RrY)'d\:T!kq9380'-%7Z%X&.pi2ua)\Q1G!N],&Z4XB;As3`[
+&5b/N:`Cm:-rV1(?q*l>73nrN"ihK:F#a/_4B'(fST6GAB,DNig_$e;+2@jmn%rVa=Z*C:2<?e9lJN
+9'BQZ+'9p%\<%QF\)!b-5#3"HHX75j1W1HG&e@)9$,,h3C$#<7g,FV9MYA)bXfp1:,@KaPd@1Sg:Sq
+L^SN4!lC<ACLhf(H*I!2JAd1nXg]=<:3CSX_fpYU[E,Pg:U?a5"=-fK[DGa$l^WG6,l\F;okU'!0a2
+#_pet(`mlf),9h4DD*b>g"NgnP"%0ju1F<JC-SX3ajNW[ApIg>X1gMH1T_(%kEfWDr0/Udar>[Pa/<
+O!pKe+,IHRgp>G_)mKjN0VT(Fe=44seTFNQ1^3ErbbE+YiFT&/cOi(E%5^`Jim+biH<TP=tO+S0lbY
+1n@2bf1Ba)DG^%(;fi5-pFBhkaG_u"Cln`lk0L/$.8@iYPdpIHL<gRTeMP_>#.[L9giYI3!!+hmo=4
+#g,u'3[5EZf3ELBYiUps;?:^o!H&9ulhUBFR0du\\Q1kcOKLf.V\&JV'=l"$pt14M+t.J!mD6(XFj8
+8FCQ"A#j%FSc2`;YRQ$c`h`leI<=2oh/;U5ID:7AnD]G3CPf=EKqbLjU#!3ISt^C?GRQ_F+$t[Uqa3
+uPtU99bjd+cMc`cM=S8(^'O\="j&&gRFN.o2X!KLNZMsN6%<NI6V'RL)EB=>r0^sQC1;n7\I#h&Yp[
+*5q_m)]$^JscaqJ^j-eaZuqN+Qre%orUG63,P0J,fnAX#^h!B/S%LW)Pr(&P#+t;&HZH0c>s?5QDYn
+IR,->8E>q:,SEfqNlkprflXr:0p>5l;d$JZBfDSXkEFTkrddA/;!/G%2'.krBYak3H;-Ss;5mO[Q!1
+S%YnhmV+Ouj+?*+5E=0.Nubn=M7QeCaAgN7bpDk#O"='N)hnThf?XLHhT6)XcQVQ\WW2BNNf`)bg#H
+n&hK!,=>F<K!^?")>7+1QsB@G"\ISB_7a!2;A4tX,S6Vh,_:!Z.WQjQ/"Gn#W15aEqd6_T7Oi;E;5r
+02#gLdUnXN?hH)q8dHPLffS/Z(V:(@lDd33*J&1+6Gl3dY:MML?'*&3;s$si_nZ6jg\,ZMrD=WL,00
+SbSrr>;<'F*JXn'Vse+G>si#!oJ6')FIRP*i.5YN#'O,O::@QG\W62WDV.,Y&J8X0`<6)JC;!#K<rh
+d0R/?dKgT(d.6K7/dYJQd'UulD\GYs'Sa$3UI3U>_QeKT-8k=PS6s"j6nHg-/Bi;H8$+=l,"o66^EU
+LU851PTZS]tEamFbA!!SO]I1*.?l3Np*PEJd'cABFohp1iC1so(Ge287B$!d^$ZW"760N#3"*>C[I?
+iXoc'X]QobtX&!Jg&K'J@E\L\oC*eYl+l,eJ1eK<DSlXBin"B*=XO$<OH=;cZFSZ?:<;$ctp!7CTC-
+2[PBd92C>Dl_&G6/Wt%n4eYQ;CG."A2=&k\V3M^hp%mnuneZ3]A[l)J$fC%*i!'tckhfp=\94Sbt[X
+@#">*YWpCYKXG@;OI0bX$eaFBu^`ZLns[L1.1FeEEl>!(V:n[uKP'KPM7o:bC=*ohjY7:&f*AQR07H
+A2lH[P@Z^s?^NYeK:Z_[/=nG`=Lc7\BJM5Vjc6IQ?!2\XoijYB?o:XnUL^rA\"[(%"j<:u]!QGP7UQ
+=(SEmLFG29V-"BbH_.n5;E:\4f*4_Zi+rG5:l<njQi3(<_P?b3uG^*l"2G4bh9`kB5\Rfen+KZk\"Z
+RD7_aI;<TCIcM8]XKN'4tU:7_Xk!]%cqX^G8Y'@)"+9G^`9O4enY*ZAI3kmY<CT(>m$_$?-c#ATQ0m
+]=ahuOj>#Wd^,@"`[OVY&pNF8m@"GSeG'X-,h'MUOq``W?\\7kP#Nu";O)F0CDStAkVnMi8p3jToP1
+=0;!LkB_?aF233[VP-C06LKkpMOopHU\DbTDD$76gid^N^TZSr'mEbXi_DVuTTN'Es+#AR3)m&i:,'
+K7U7[`PD6GMd/i<3`&eH6$Ie_Tl_qQ0Q=rZ^]9d2'K7SHjS+C^<s9Tn2MFuE+[e*I%#d"a@W:<Q($K
+ae%_*j>&,mZ72WjL-j(qO(&hQPY:iqr^S;D6=W^P=p%iZK;MI`8V/!Y#g@:WW'&]BpP@f6oVUgfAg6
+8BW"T+k%"6&5bc[kcKL*2GEHJ1!c'`X)/\<^\38Z'hm;q#KJd'NSc8@M[%A3@@BYcl4@8436YW7H<(
+tO0M:C-)Oep'I8s-d`(WE6H^S!bb^X/5#\)HD%C0QBdE&)V_o2p/>b80QA'WH9:;/6-/&T65agc(\R
+8T>Mg:3FOuB>NO#LT+aX\L8qoa8S.;!l2Q_4BK8,7]pVf_BZa!b_j(IpJs,j.IJYSOuP@l7OKrgjf.
+3)0OXfRW>^T(51;3u5>BkQ:RRoEpFC.L9%4$>uOM2LHY400:Ic';Q=qU741]7Us[^6.?ff:>/-0BFP
+\+PNmTpBQ$KSFRoJ:lA&9T3he'G5@Lq7WD8l59d3Rq61]m4:.&GX?3Gj-b=5m*[-JJW"]n)=c:,u=N
+<lON%iOQ58^uI=Y#Pl2?VM<;<jW3ML8g:IeTMp4oNFZ$D)3nH3]Y^m;$Eg9;QZ5fdSqE`)b;54Y#$m
+b,1&Ad9pL$^Oj7dO[c!`\7?`Vo$D05b6IMq;0!JB1Z^W(Vok[;FZ"UZr_@"CTf(<aID%WSEL@j=HbE
+0'YDUD[t*,J$kS[A)?Kg$<s!$#.FZ3H&t2%,gbmW:$qD;I0Pqg!=$)6cP.9&RI";N'O&'=ejDc`hb5
+0WoeVAQMdbh.t[39o(BX2f8'?e<Y6nD#M">q;9li#AnD."hdu8p>@qDCY,TR^/$rh,eOUhmgZF#9eh
+(NH_0L@Q"jhuZOL;93+n5)p;&CD"f0?#4\W!"NE,C_;sQ:a0XR6D'q3?V/5_18FbD19KE,<e6K)o&9
+Y30$`8a`q&826S6aF0?A?of_gD,ObX`kk_aN[(fc1rqH\E$tQ=b*ei?ZRQmedMDNO00H^=d84cjba!
+q%lKiGR27L<%-`cXhE"QFQRQNkEKEmq6sH)^3bU='SVYimcV3LNVL5G:o4E[($:?O44VH$s>%l/A3s
+\QX&#XOCT@=d7;//6cWHC+seJb>cC;!cNF`st>)TPur4^V/^Y'ABr=%fELrK[$/)V7%U@2*@"Tnp[B
+L:[n)9<kWDK@#7n"#r+=Yk/:lEgO&5D`-kY_m6`Ehq4f*edUBKV<-@V)T,Z?/B;?YK[?+i^sG4G0cD
+BZ&nY:6R)A,=.(?:(FPOM4kO&ur2:#Uri(5P6K0_7k[`UH0U,5A&cr>U4MO0HJi4e[(ijT2R`Zads3
+tSPbYmojrWP"n!^B+[-GqUd=*5$rF?<b9CIfqJ9a(t9W>;PV\AK'V@7YZI4G">(-dY_B6]<1gPQ2_u
+fKd3MIRAa#/&dCJ],h2DAZcfrS1Zf\I2rIeMIGlhgG1lA`!]sL?e"A%hCTrDiNH('VG9>^j9>"e!X5
+8Zk)!bK5]o;(se2ortk6<!XpiIN:pb`M>^]>^BVDN_t@V?m&>J"ai1X%j\>NWX5Of9E0_>GZXoc/Y`
+nr@;Gq,a<_4bJoDo$,ChHAhH&ce/,U!6k;[Vsf*3_>)/rqM[tu+I*c&*uXR$ieir9"=RpmJK7&-/P;
+)D(QM0l5No]YhY81JXn+`ahu-@0p0QqNT>!\gIo#Ft5Cg(i5N2H'7lC;eGJJR_4j8<^com<]^04Mu+
+N$$(!KVhlJQe!<6d!2QS2=ot51pN4F7bt!n\4PF\Vp'oZhM0J%RB@O^%dN$$kU0Q%m<;m_'BXZ)lL=
+^nj,A@..dS".?-!n)'4=24#j0l;_'MP8fSthV&7*8R,5WZnMpE759(+u4:T','0m5Z5MQ1R/,$aTg:
+a8_4ld>BUZ%6g.)Ci^/:1S05esnB0b/fbXndsFnVmaJc'$j,5st`<PS_3<(rG>F_ot50Hmbbd,JT06
+6ehLQ1d8eS5sl&;0ROcHlYNl674WGe$H]OQ"+-E9A2]7L_CHtJ"=q?*(dF6"]hAF;S.Ini4[g%Q_#+
+R-oKGF%r5:,=]!M?($kBp,83%)6$o(>>FBh4m*=OaHZQ[1Q=\h@/]>#U"6dsgZKNQ5f6pri^_K48H,
+\fL7Bfu:L6_iDIi/KlEf#G'I7\!CGn?P/I^G,k3T>X;.oH1S/Y/1kZ7RVAe42+*>H4%l;MsD"r^ril
+d25!gl[iBZUjBK1%K0uGfa69Qod'<k.jN(L:`W4bWU[4DkilJKJ8">COA*lB0NXGE5MXcNe[#cHTFp
+fR(*:n!>>[ti+P=^=_aUkPJqi+1'WA9uf*:R^D';im!S&tb*8XQRj85./49Z]Q*-VT&\oV0J"35jmQ
+b)n#C(ooVO1Wl5X8k?6OKT)>CR`TZM%1Fm.ncQE)s2)t2_n9XiPMO)TXN/Oj6u'b8J>]cePoZW18Lo
+eAgf(Hch8N<r]`_;)bX'EW]"4-:$Rr>1AAec&?-1LJ,;Z)&oM*LKH`l.(`r&Y$9X`.J0$J:58uSc5"
+OPA?Xc"`cLa8:VoW,#49h1^j5QiQ*Zt.%ccb4te7bE_p"4fW2gqX$Lc21s8r/\_EhaX^+]i7;=9S>k
+,d>F[H][YC9_d/";,R1WF)9^"5e7:u>:<X,.7:]4UbR1rJnO6.B_ZWiRjR9_QC-)!)912^noS#sQh+
+K$Y7eFY-,^@Y^X\D'q"OLhugbt+UYcJg)6mVXk"2RDW_Ed0a79ip59X[c'##MANbiAUs*;.MI0#;YR
+:\_7li2k1%j\Zq/:^Z-p`9tbF'gZs!4`oCQCd-&_AO?#S5nm,0>JS6gdmA`q7jSPio\N(@g<iIYd3u
+(VeKg61's7q@d<)WWm2/[L=2VCK:ji+-m0UK0O4*,2dMs^T'QMO^0[G,#c?+ccJ>k.P?IDO5+V\D6S
+HQmlB$s+!:F&f`bPbAY&5`98:K9,K$the@<BVnY;Cdr/]F\"H85j3#X0j;ZFZCVTotroE8c7LCqpSK
+_+B%"m;XA<qr>`<Mp<t$;5O<Af2%*:jcpn79dWJ*<J:YL`s4"=nM[Z@SXM1E.>L\!5ccm0STVoil'\
+1>FNk9=3m7j8gk"!O'(KFk\7:M-Bf2b<g1$m?<eLENK*(JF%<hkZ'"\LeG-&T)k<Q/f0lJes/NE11C
+=-[[$Lq_;RrDlN:(mE.dNHj'GJ%S3l$EO?S212,t#hPcm:f;s>21Q`jCC3,!7's&J1*o#'*S,(G$ff
+l+AE$9FgBt%m0g+P\eT&[tP12V@<IIbJ//Q@oL^Gst:8NiB>.@\Z4&!=Sg!u?f<M%,<Ef@Dkd@@Ye%
+(/Ap%+ZEE75^.D'po9_>?EJ#1p(':]nK(<$sF@jg.Xo`2,qg8Ti&V'b<6lr*>)!\;VO(+fFY&>bf<k
+\0Wcm7fL_K5>U[.Ygso]4;74&7"Bs'?gIjs1e5Z3(N,6)=^t^e5`N.tHr>\/Z/DJ)@eqI6l*N'1ms%
+BK'UCEVaj`ne9/C,WFd*7\Ih3?Y_ZG=Zn:TOBK<CL1uq:]@F73l]u76SMXj4WNb>?IlHmEF:J@&.).
+gSLsfKHo>2]g[$V`GO>S']N"2O4?\):i/ZtN#'nhg=%>ZhF&5dY`)\r*_M^B,8H&?m>X*u#i!#.<t2
+7]FMC/-leDZk5FbnAA8AlcECR(q;C1G]`"l66pW$;%LqRq'Sadp:8_8B>h_L>Am6=c;%,(#^hGs>W/
+Zcrkj&u'Sc].m(L&Knp%+EF@i"1f<AVsdj@E[3lfu*78K_&*lmGQP,^pH8`IDsK:,[[ZThkgBPoIX<
+ZqGP$)g"ejM"sLSo&VuDq?OdaX*IHCm"h"U,4WJ9I'L:$)s'h3*b>fEb*EH/,P$(4N=QL"I<K9gCeQ
+WLod&gF(gV`#9Lfbpq?nsjs7$,sh-J:8[@PdBe4j#rp2i)l@b!%h\bN($O'jA#8PdW]:G"+IIguJ@h
+MN.1:Q6nN_n)QprjAn_1E<]t@U>UaJjH-;_9o6qt66pGB>FM/<XbUJ0[cJ@(Tr(H'S6RB6-fJ?LjaL
+L[(0HGh=il\',pljV[=;cM@u08S$:'H!2IPUPJQ0W_j^mF`7V^<qisRG1aYmQR/Xp<SLZNDhB+pG?:
+nuh,Nb79Kgr<g_K5TinGLo#p8P&PH#'?[kpd-#*A^-4tL3R5/Kh"gmRaMI3`FJ#L7,_a,k8o,/:4UD
+g)<`E!J-13.[QE\RA*@G-kG42-b^*pABkIWbBYKF</XXmKOg,C=kLP;tes'c9N.uLmBl`V'p4MGWK^
+#(6l%Weab3e>ODiDUAC$q-sOKW7#TrXJgBjR:nDPUA=Qteg_.AiqTY%)438nj#XlFN0j<h!]m:$UT:
+Bdeu%VQcsNY30DFh`eAJ2OJ"j[O,lZ;+@SKCX27#Z"bg]X?O7nAif3`YNa'@:Y(nB<l$(/-YlJCBBI
+*J*jLON7r2X4@8<I)p2KAW`+ar-Cq^"--3WY3[:!Ukb]]@h7aWD\ZKt>`CgPR`L6r0fhX+bu?4N'3%
+a/^JT^?ofD7Tr75-JZ1Y\i0gD0<;T$4tsOiG8^qmOXjpF3O&U&DF#8Cp&n<I#r2ghX7B4l)ro\Y3Ko
+L2Jd>lD+<ubVUFf0hs:jDD[*l?dq%oEg?\J(mdB"OI!TXQ`,DWl=5N"V7ceR6!:L2Pm+23*m^MPUmd
+7Ib?.S]V`GBKjY?'fRDP$]DI;86WN9E2-R'gMSY/P0`%;!!VLrH<4!K1iUl#9,\E@t+-@'"(/'pjBA
+nNd*C:Dc8Bf*6F$ENr2V*n9UQea_N46t!+b`upR0_XKc.EE=AFk8[>`-5=-/n)jH7:FK[:&I?D4Ej6
+GK`sH`]$?FmPEPQ3^QS=U[mW+p+nuji/%l*R72CZAmELGg,?T9qc1!F8l&T#S97h9GI4`bNm#enB%!
+=%n_2"LZ(oIF>@*sZmirH!HAE`Xr:HURHBB+RdAoVhCSG<YCq&+nUbFMCB>#j9=jXDmW(oD_^qY=lt
+b<Y![no_0I##?We69CdR:%YTd5IaDPb?$*PA#fdAI!80mb?M!nup+%Q`\7\+:AW>S!FI,%1Ve@RKB#
+WqK%>Q"q:MOuQD(7JVmuMEQ2SJfS<H_Ga/O*j%F>J,;`H(E-NCOo]I>2nVN-9\sN'D$"T6^%3I3rTM
+@ul-IpMooqIs/#I--(1Oc\2`#.<e![F^KnO06RPD1jG[omW:F2p31c-MYFW>,5hT<pnU!QJnqMbq(>
+,3#`J7,Q&8?_Fe8U'#FK*FQADoKa+'Qc5oH`8?[5G=GRp;M[q#7GV"Q1(ntuG53\bl`B10e;MEaFPk
+@FA^WHrc_#`k2Ga,pnH;g:;9pSY0eDl8>6UO+,ADC;IY8#uMZ)uDRFqfmd?Vm^i:FShVAqU_j1><Mf
+(KXL9AGj`1js1!F.M#0]Wqd6s\Vcs!Iqti'[H^D,72cT[h[sWJkI#kFWT>:@@X*c;=TP)?#G)(F9O2
+PDAq,brepD/]HR<p=6Gt6D5B<qFpMg\++rAW("Dp\H^nGOJBI.seHqYY*;hjjH!p?/=)GN3u[jF#S6
+Lpo/:IuH59kPg*brfDs4O0X,9li!aJrn#a13,@s>W@P@CH<2tMBCSVJm>-Y%r[0^S:XFMspO772NJa
+HVk^X#U!!0De%0qPQ@8OIE24OXH`*uS'UfK&`N()ZEO9@U-+-9$(;E6"g9dc/tAQ$'L[TtPR9P(I7b
+gn-^R7N'_!Gc"_5G1hd<&u<@N=0O0!"7LC.VUf><+aOf`8[7fXB'+:]&e+K0rNNr<O@u!gL%<kD-"8
+Z3Mcfff'G:FV2D6^[bbq(]B/bb/@jSG<GK]Z!%bnEEEKk`3t7"V@'WcO]NY]%b[tp!]]=\IP0;DCi!
+YQh9rHK5CnM/"7jkL?kO<egVUo[oU[5.p)Jp`"1u*%p=ioIm\[pF(o!)K`&"V&1E-W77lj='Hlum1)
+BGqAme)]rm*8];6c0)N[16pF@QiJB'I"#!/kQ"<&n+_B0*aDXbq7mOM"ID8DKDqVV:U1?/_2rCG1a$
+DI]`Pr`S&Yb$&Bltc6A_cRU:maX2\Ec"W(^kkE3$kTVXYp;(VXkR33Se_<+-`Vd!u-'757_L(,g0NK
+d"$'e3=L-c\.-$[.,tM*llQ*0.';SX"bJAX$g^gb0oSh*Cl9GU;9A2jLm@o%nqqh6n2`r2m%+@d4@t
+-*2bbl'?Z4o1<WA"1f%'XYR\N#9_g`nTF?lI;3YiZ29h2%1Ik?#!AaODlMV5Jd55,Z:XYK_>-s`3)5
+C#.$!F!RKkj[W+&fRAAQ`%)1=Bg77V[?Sf80O2AuCBc>ro>+]mF8926@S#Zu5Q!B;$RhbdH,"h.(,&
+'2=`f.-rZ-9\VGhTLQ0W<J^07G7E(PgM:;"4^E3p*4T8*3pgE`2p>]RXbk\)"lE;Sd.^8cV<kcsp^S
+#NhhtTQpBMO@.nbQ6dbANXf>]+r^fY@'/[`+Lo[0+Cc7p'o=Vb!.j3(;k(4ZUc_3N7=)L20hpc\(fk
+*bPYQE=.l7A!94)?pp0=Z_h#kaH:XTIis<!(gnQW)S?+\^#<>ANI!,e7o@_ZZ6ql(;D"2[KXCYku%G
+lZgJ7I_R,Fr*_X#_'%mu5D688T]Pn9sk-Ti'[/n(\GSgHQn!`+DSoGa-s1tfW;1DmB:gpA2`nYJQ$Z
+[657BL9>oh-=tE#]Jj<NGQb.<I^KAMJ,HnZTgpI@K?!Yl)Moch%jrFlBk&K):>crZfR!.9Nc$i'Z7K
+Q0G4eU=HiSI\X-<J-M2Nf@[ct[IL,#ZISAih]mg%\/t[CNd>&6jHP&8:RD+o\@:VSP>?@4@\3^4IP:
+*j&f9h:?/R8XckO`a;[`XE6i_Yt`UQ47/4\VYBjP0I7mV2V#1nEaJ1I>P60M!4TZLjcn3-E\Eu&HI;
+2g0E+p#RE0+(?;RTtB2_o#s]#@HuRE)95f6Wea;@DQU\8%<0;LlPerK.mGT7N"T]/J4_(o8+cdlS06
+^?9uH0DGaNu7>S\R,2$Xg0![:!Z`O%%]OX7SRPqiMdT=G7^]_fO3gJi]'26n3B5j/#_.`7<ge]=SZ4
+sCY#7P5*&Q3Q<1&]16^<hV16B[$Z)a)dK+CgNmNfn848RfDVL&=]1Ka;>%^]:^:KV;/f<`R1QN+V##
+R=TD.R#Q5A#7WMPEUj`K4ul;<`k6)>ZP8q:@t-,kN3Z;YNb18-NufTgXdZ&s<(a-"1o-YrG]R,nNL!
+rP)r0F!DdX@&WIm%)S@"h^NcI[HG0"<a,n6XY7`3p:3$tHsC\-&ZM'LgtkRf'Y1``S7R=p-i%1-au&
+?j$Ym1h%3%\h?Eg<fSG?7=!rU68i;;A'p7O0kOQe&$(PB*1]Iq4eP-/sd,W3k5].\"h8=GuIbi9FC[
+LT="B+#)[C]9sm'3'_\7Y>(B]*PPD#>At,@@Ma/b'9kh"!;ii\-6YO^mNKmgQ;VJM0Wo['Xe7*gQBj
+PcD<"t^bStF2IE&=LUpmj^ZK>Q?a-u1\^X**(M=2XE4VVQJ\e`bdi(lMF2'.^12VM3Q7`DgO0c`tl(
+aB99IABR\V9JZ*Q]"5UtCtrU.[X!kd!n1.Dqdu+'4ml6)Z"dd>X0mm=f+sHaYRETLOJ>+s%+YE#/]=
+Bm<pbFlfBk6-D#TKhU2u0\K[]0s&\3h"k8'2[e:_[HNhEDB!]crt.`HJ@Csqa;VbRQ"6s1*l\,\I2I
+s,^8lWn_A[90@fH/UI-K6P-'>a]5NYLT8LLL`tTJZSjEn="pg;Xn+@dmu/em(m=F9fmnF>9NV"+CML
+!1<]3>0Zt*DKs5@N3OK*P[Jr]UT+#2!'T16HrWa*^rJ_*6$*7_c_Wge6=Y)IVK13QZ[8$H'.F'_eOn
+$6-o'KsfH&Belcc>'A!'EQMQHfCkb#m+:AS*rg$eU*GK3I<K5]$V>2+V5fOQL.kDWsu2B[.L;j^0bJ
+Rh0aASiEK,?bDDHZM=S&!93=U4FNrY`a-f6%m&oZ<M@a1:*=%F+M!Tf;MjNN6(/.rl".2i$i&&9g+N
+^lOYn''IUYQgP:Gj//#j"KdF8/`60T_r2=jk<V+>6&?_)#528P+en8&(6Cm`nkm&g<hlWG@dMkN$ic
+e0WqB[uLKgdZO7^4QAtlqHVm[`\I$AghGH]BBWElTH.ilkSjR8%I.kl-S)A*!9o(@J;8r&l:en,V?3
+ZGLG."Ai+2V!gfrj&2nlc!+tRTpV%7N$!]SD`p=%O$&5&%?6_RK?U5X7;I9[Q]PE48KLdp&Fn?T(.s
+ih-4]d;[NT0e5FE5W%bE6aWec<1J09NC]V`p$].1_\X?@9+>iLC'Hi1>$jZdJV?/ArO+N%8e<[^lN!
+l?XtTF&a111fmjT*B0S_oo[`u5@Yga'%nasT@,es>@!eBAbPQLfMWP9i.<e"i`.Bb7`@>@rTPhUc1B
+hu^OSk*X+,_/8&/&R*<^T87JOg5j1*Es<dhd<#*1^;K[1E.j%%7D5*iXhinX/tkL(;hTJZRC/K0"&/
+r?:"dX3E'p)N\Eq`U)&P-EIK>WYB/hWg9DW,:)c!+1PcT!Ed*`q4a(0*s:-56KN)6st+"Gcr]tP\6Z
+The>o6;k>e`*sCSU:Y2:jcnt`0ee)/Fm!MSqrJb^lK\d.Kb0a#IrhKMrYOMV/)@oXU;6SL<YQ.Vjgc
+H[^%A7D+N[PhW`<*h9)\8;=^h=1[bl=]cf!$JlO=EAdT*#W]&YXLh:CK;cZ5Q#TnO)[HDtsHqZNW#a
+hhA<=TmHl;W#G_9qVuH3TMuj>UoV=X%Bt$Nn,3-'I/P`%;LtDX+WT_r]FuHc"]'e-+eT!)V@tY>"ec
+nS0VVU0HO?u#$KXMW_$1,ULuNt*)GJj>J8?,i*;PK)#6>&?/%H+nge^gJ6*QRm!Ncj*)A=7c&O8De@
+^[043Y=XL'/4C+_6"!iOBsUbp/)/gOUa`%Se=:h#)tnKcK5?4YSoeR#%F_S+X@slYQk`M!5YT<J6!:
+[,j4Zp!`;9[;+<s8p(>)C%]pEJ_3u#\*!L=e%0<.*V0j4)d2$+j&]$4?Z&l$%=Uss)cKbK7&V<E5L.
+:,Y)B`&sTmn#$<!:!?)Sg:p@2p3eYSpnM"^r,f+PRt]'cu>3*e>:ITPtgb>9/e6"MoO'TN2saG\E4(
+*,nSAk5lR[cl+&3)Zb7'd5)M83?tgm,NnP7_0R%$"r\W3)H";19hQZ?pBV!l);rjF6)5'#V][-<(Z8
+LBE^5*S=r6-Q(SMfe@0RW8<"0FcWR2"uO+tscj;O_`)<!Cc5\pOqD(7<5';q`Onrul]b:@06(\'dA`
+*Fn!`(k?:/@&J/P0k84cRj%EAJ02>1?C-/kq9:/0(SNc1A*;@q(K&P0Co2u1BfIQq(8o-l&"@R1DMW
+c))8H<1%QO7D@nSo&Mc-o1@m4V1Gpt0)H3sK1\3mh1IX-A8MmbJ2"OR%1-[RY=Z*Nk2=k67.[N%lBf
+<;72Y1oI1NbWtGrN'I;)<V[1PIf0M)_i$3:i7m.'5HBPrZ1A3V/q*1Sm-RW>G0,3qKU<1UT;c\N@-E
+3JK=P'>6MLaZQoS4S-r\Zc"e3DBi*/4nIVr1Z^fAkqSCQ@2%BZZh6P(q*24a5NrAQ'D"I'#sbj,5kG
+XLo9fTr#+B#='hkSn'Guj>+[P`66M*!"1c7X6aZ'@$6fO[aK'u%D/3h>h6^1G:1fZtd=HZ%L7$M+FA
+JIAX)b*e27eC[j1j)%t4[Kiq7^P]NP\EZfD+A]-8G&$91UBHu91Tb-2H5<"Pa+j_WCjP"2q/X8e:C"
+eUIk)F9=1lr1rW.1aY>Tf6?Ih,<.@M>9U%k&9GGZF2!%JSkX)WDF7eEd[.R4:q+n)jS.qSkeHJcl#u
+#I/>kEG6[0oiS),[bF;"Yi,2'l.C"]?'a;Y;bC1p'[+2,gnG;tO'gKKW9L8Q<)l4Z,VPPttD&=]Mf-
+<?eJDeR_d(BfK'.9iQgJ'I-WnCKIol=7T?[oXRciM*uK;=S7eZ1[RX&o0tSP=]M/!25FkaHVG6E8@>
+@"276Y%"]T!">4nLlQ,R!NaL=%?8+^4lFj"'5firRE<ts+Xp"Neqkuflh?FB<123D5<oj>-*<RpnPp
+'"iH4^^/S@.k10edZ%G).BoJ@<NZ#2C22E"_)X,@e:1?(,9<B3CT5kA%"[61bWA47:`i$5IO-op/P[
+Fhdn]KAbKOoQ<e)\BkF]HAp/$(2K_!fEG'HCBCg1W[Xi+8M)Ek<BXX%;1F$T,Q"d[t3nBp<2Pi;)R;
+-oIC?6%:[]sUk\>/c0C\GS<f!T<Pa_Q(#Cpq`.(=-hUfk^<5D78D<p>9aGl"TkSDRT(L(@Q0"q.KEq
+DmoaZeaG@o"\b6h0=@-co&XQ:'f5$HEOR):'-J5;Zl=3@Eq_;02`5Z#3HMYmF8%tB+gr=UZ3O;ME,q
+^r2cY!E=`q2ZFn]<f2cjg:a8d#fG5$!#2e@0!D0K'0GP>6`M'[B_M0QLWVg!K4f9LW*R<>ul+sAcU5
+m@cWWHu%UHM=[k2mn!V\U1g!Hf/cQ@CR7X:0Vq3I.r\@f?o"j?[%jiI2AJ?fAD%$EHrAbIeW=F=.TM
+E3ZFcU-c*KH3!FhW$%TMpJG9_-3#.!h'dA0G%2V_p\'9C]l$ag+"+e4>+he&BT6WCFH+2U^pORq74b
+Qp%Ib7AK2iDt?Zj(aR)Yd`q3+[hhBnj-7LA5bD3-C"$?k!XK1"T9U=?Uqs80U#I)B`Vri,/a-UP!X<
+H$G)o32:lr6\SV-B\5h4fWKH9Vi+W#Lf594@Cq;^ac*aSN.JJVfZG*5\f/)0Jp1H/D%m&%:`L:9"1Q
+m<\1e+qU`4Pd)e#NH@!.&F-3dm:!2'f)i*HoO!XJdr![9#s5bJU=,TD;F*'"Q2+Nt<o+cEg/$pXe*(
+Ya5f.mDQnN^<pMi"?oPWHS&o.^r^h_$tNp^'k$"Nu+.C=RCPR+-cQ`Njq<=%29dbDi>>J)dq-Rq3@@
+nQ]3uU%630q7#dPL`WMlk#U"tHEiY,MoeO@t#'eQ>+XN4:-jCe(%tJ[1+U/0ZGQ9_a!l?>jTE1UV!Z
+Z^t!Pi-7+g;9GUQ`/t"(BBB2dM;d4c1+OFnk'eT^iIU+dKN\M\fV'TIH491`Khk&6I2E=S%lj&-*TK
+Red2;3YDP+8/X@ORs/q!pr"*0X/3C5V>=Vt3b>17A,mN^VYXYsg1?7)@N-JsVI@`/\DNa$4-s?$!;]
+@h!QYP^$5k"q"2IM0!<8k1l_G[$$5n\E\t>u`V@u4WTqO?.)2Jg=$68fp1*AOp+@I*`WXhCo)M%H^5
+XY^b#QPtpP(G.b5ai(t-jRO1+s92PTdc-+,R-Q^T@[HR+9WOsTrcjD$K,.q+B*PI+gP0q(uV1n^^q$
+F9n-?4!'u=*HBnQ(&03]<MRQfb>.ahQGH6%dZb&`7ZD4h]]73Wd[/(qg\h0ZiU&t0=Ip6Qc)dfZ"_5
+op[XIC5Q4&pDb0sb(EZ25cOHZ=t3IAkk]'3gs4HTD--e/UKp]6@8!]=GQ.T65LIMHcd[gX1.*`O'r^
+\6EaAGf,Jd?laMkPs>`^>&h<'CVQ<VVcmT.RU-pVX;]fBVE!7t24(8/j0b&E#ojob!S@l*\/?EE_I9
+qeHV=gYbJE,-WA:6cr$fNL1^SOL*MF;eJM[gDS[rkaS)u745Xq0\i"K87,!ZJB@P/$r-j(Y=$"+)@J
+g(T\"9<L%TV41C\Rl6.JTW(R&g60>U"sq*T?99o.Nn9(!/^i*<I\7#&j[n2@5JL'h?0GA)-gH@gT.j
+C-`d>+`*>+*grIXOcbqq#`0kL"RRtadO*2CVFWc7Z=*r448]99K`>hmsQW^u[29S+WbEAXCT_$>&ca
+oR'_>G>$gpbJ"!R!`\PZr^PR&/9f6$6HNb+,0RHc<WWV8F9)cMZe<=c\M^T@UXANkj!JJT_+r$eE">
+fDU9Q4a[5ML"O(ifU[YS4ak+r>92\/fE&=W=enK6eec-bTKiO__2lLGYQGN4"(8A`+Fk!7dG')WgVG
+]P+lUXRF9>d2$f(P4J\D?JHlAMeds0E2+sme--j;Uj,(R`7!3.5.l2V\=!$LtD'04/Te.Y)"!uj90\
+VLnaZZj,0.R#Ap!"7dol4$jlZ,!pW185*o.GcPtQbZ8t^^:/Ea!s6sjk\>FQW</G]@:"+27a,&+9de
+]\(uC^k(/TL*Z>Q;gYMfE_:tC<Ehh[#UZ28%TX[k8\F&#'ZeKphj4Et`@'eT.=mJ7+UcXf)hG`5O/a
+H\Dk2!B*h7;`59U]-dfDFn=?"tE'Je,/Y*]kJF!6ltOj:,"ZSjCX>iSjjNH2n!.#f$QDh0Kt;Oma5H
+mrG!?6&2d3s6`dWZ2m&gI?E/&PpuV:"EL(:Hk"^+UVTkFLccX<+:8rg=asX;ikA@Q+9h"TZ`=!PG2H
+a%5@tQo^(6mJ$/Rud+FVbKSME@khQ_(X+g*"s\d6.W#p<OTi[,)J'I"ZPqOdli\bj^^?4/k[.NnKKg
+7'Q7rHH#s\GpR5!7h-RPI%qh#_/KO+5Q_,:RAo]&jW#gTGQW0`#o+i0F9S)+d,:S#"iR7!.dD.OAH&
+q.2@_j!&9kjDE/_u8)t:#'Qti>M\'!IUC^lMRYepjn2MkEqHYHb8M$"p6;2.p3$PT\!bg-dKn3g5kq
+&8L,H"K#FLl#Z"9i3hiKO$g()?nGKd'B=Q%"#ZH6fU.'\+B89!qj'crl#c,>=G'0,L#iD7\>3hs^!;
+!6YAgHBN4.oSKh('4NcS^]Z/Ng5O(bM:_5!Z,V5aTsIjk?8iqOFW=OEjot_KO`@Rq^^Mh1\B_lH"aE
+mK6Y>%i[;T:k'P%4]iRDbq].uq1@_$OH#q.6E$Ki[-/25gC7LD:&%nk$=$_3mQjPBV1S&9VcRV*\O]
+Mm9>1c$.B!_1Yf$jm4aUI1s[&-*pt!%Oa/.&)\008ke^60S`PP7-;0*WhGE.bIHIb?C'qX%FRpQT<"
+30L1esUX'03&RY\I,0BD1/V474[-5(l/56g/0&"a_`DLH'W(#pS)Boh[fmnrIna(5`4:`+Ho0s;oSt
+W3HlJ!LSEY=op\P##R.k>TPish_4P"RSAbGm!.U<+rD%S\I$D!j;<>e9S]Mt7:l0T6%n_4JrQ=>_bl
+.H"ip-."Kd$d@#d^Rkp#T%Qqq4Ug#L!5e^EdjBDF9s<rd7oL;mo79%k%P:fSc1?N8@t:J/Qlc\;"I-
+.AFfHu(J4%1u0:sA]>.[Qf>LX-$+VC5ZO%,hA4W:2:6k6rpq0XRrLsQD/JUe$7$3M^'p+R^ViPoku(
+.FDFbN@HGE<TF;%LOTd.E(DB\'=YMhaGiV2+R.uNj):qF,quQOTVRdf8`T79k"Dc2'?<dFr!dT+=Zs
+Ja`s@iP?7Ga2.>.<.Y`Q4kUm$f?jLX'N&_AB@9ET?#$dL,&ihcqW-ODH\S%kDCpdWMapXj!E?82D4S
+%WHiD56cX/aMBZ1gNg6K8<OJ4=hXG)rQ:SOsdahQ#7D['nJ4l_0WZYb(pc_A<Bk(9.G))QD]rCHBXS
+^i4Z);lM`VC`eApdJ/G%%Nsu&INjCU+=LV9D]Qo>8>%>kLS6CZW*R%sn.#Y5Oe($FA<:D=Ud>%aNJG
+DJ,RKKefY.@dB]-AJFK$7o*iCEbp-B?WBd,NmXbmMIq0m$74F'7D*J-Xd=!/mKGXm:^nT(RY0He$[,
+KZ#'a?/eeS:Ab?%qg,J%d%*j?)Rj9Ar4b1]]'=F*bRb%M^\4(J>dJ$-`H^06e$E4*Uc/r<(.jtbCN-
+"jbpEB-@u59&l15>%`g:-=t3N(:Hf:#=>pIkM,J`)p'3f[SmM]nJ85Tr_i4<IeOPg2+)*hj&$X3@Rr
+_VKj6aV!QF.5-5^X21TFSn:$J\/+IW0r,_)5/13LZo/2f9>e_[!pEbKLMC`COisi(=$d31"7?@'rIK
+di-<#5\0qK!!S-J(^nD)#=-LI%C*&n`n2I>@m+W?T]ASYcl3#hC^Yao&c_sk)e4Ir#a)TE*hN2L#KU
+;1Kt#&KK"*E>+Xj203D)k43)Tpq+?gFfkVg94Be&T"9bGIfF3c[^NDZua91#j0V;uY>USo)]<YlUL\
+mB+SVuRLN5qo'%]oI*`4-_W@!$<2]Q*S&[8q9g/@k8-jn<'!Ya^$G&:uMJ>GYJ@jpa:SqC7TFR@j^H
+b.HMi63ci;dU\TZa*ph&pd)m7ak5#WVkke2/M5lV5eC@()!Xn!RYq/A^&Xpp4DtGrCd1Q*e>,tqDYm
+%2H<sKJ\f\.7ZN,oJ:7Q#qM?<'r9P"_[,1MPB$Vj-nF;da\WSS0qdm\"@:E\mq%pb31$ZmbtT5"<AM
+9`P0&99HHM!C1TX#9h#OO3f=MM$"Zo[?e-2HGn&Y4_q.+rj9k+fj&<K=aQ7Ddah$9?4m-WY-lA2<q8
+.,h/rrB")Mh-_0-"c.oe;kN7'Rkp2sg0TnnqN+kYNk&-mG<K@E$8)[]F".9.l:^pFm+-O)J[SMdV],
+kY6=rG5);DQ!R#5h$E1%E-=6!!"-M"JRpn^]7:X_f/`g'D_bt1l8FOWnCYQD,%-dd'#AdSD?iB-A*E
+p"/-E7a,1)[m[KuT29,%>gV7oKU\1iY?A"bE%K\mP;PB84"9rTrfRT`E*tdAPhtW'lYI4.?UWaq_.H
+M.3oV`&hKtrZ1$8nqSWO6qQ(LFHnG&Z!<_Us%:?9C/BY&5B#1QN&TS4dZc+I`A=.XU/imrRlN,U/VZ
+(5MfpCp:gmYX@iFj8=IiEY_$`R27)YI#`&a'o'eqWn(5J>^CCe.AqFZ'BO=gPk(YoXZ:/2j_R/Io+k
+`V=c5(;m)[E;&ChlU[l7psiLFtTF3^3*4(hK-Sb%;G_V%A3Ap^MGElN`;q?&Q`4UlOU-#h6kCI'q>)
+l.(`O'UGB4_]=!VKC2acT5Q"?#9GNk0BaOR[6rfI8R"?Nf2GH@o[:B@B=T8,M$&M>>:Yl7^]tBf:'\
+aleR,rFr$jief8>e]ofUD7\/!$+"-1+.B[i[e(U9mCMeL)[W^-V)aK39%B[IVG8B5oS!S26IF5WM6+
+,NQL^o9$T83-#gYSFOHZ+?&^3A0*9;?#SD;hcW3#;\TS/6fsIM'GA<t!uW1OfHL2,Z2aoA?'>MfF2#
+`d$)SMu`'Y"(<ks3>Wq$S<oF[ISn75="EC&ZmH*0CbtSKU#VM^%LrDV2o+T6kFD:=F8g^aJ^Ds2SJS
+&CIZ`')=%heK2lCcsMo;`9'^-tNRuItl;$!'3k?V/mFoK50HP^1H*7M2S?>gp]"G.O^gSl8+%KZYr&
+(a>hNI]OMENVb#\UC*bGQ.^%HkrjNh@3JV_eSJm;m#HGoJhU<'HY&_G;t*Q#S6J`h?_cpX&X*uNI[I
+L]JlVXSsRoPF]m6X5oWsB2oRhcXi.@[)F0u%iW=W<<(P?(,;N<#OcX*74^Z,%T,6O4*t.V^dHj$Q^"
+"33AT8!s&c`u/!!FG6':0gBpOEG'43s2eIi%/CS7CXZ;FEI[\C^Q%W,%-S?;uB8!=QWd(Bbt]\3Am^
+>i2=V5PtLH$UMNi!=7HQ5@aE%Hhb"siW.mHK$XUqS,7^A+b69C53W3c/.Fl"%RB9;]i3oSA+ktVq^'
+&_V(5h7YQ=lV?pE<I4V.UT@o^>:)F:GD6+[N@_q#T6&\X',"6jq13a=hSmJme[^?bcSa`NkS&4+en6
+@:1AoE%;:e"'.`SSSJF@#r%3N.VB_KBqs>q;/u).)RSl6T]Y3S.27R[3Q)FUarphS0<^8(k</W&9H_
+S`%j\J5""[$1gDn'g7YGaU4e])M"CKM,U*3o)$$-SWlhHDlE@5s5K'Wr7([e6$k=`ogU`V$6psIo#V
+%Y%]e2sl`5GVD9N=I`4iLZ-7=83+MG6Lg=[fDr7D)kU]N3"q?:F3f7H@W@r*`&7@R]os`[kXi9P$W1
+A&_bd7XSl8`+I#JC.>:?5:gNg]PU-nDEStU`p@Y7$un<:DoWi=7m(lPe8iT'G"6@m29^3`I!J5PH8h
+(7a1Qdib7hpTI7NXR8,:(lgjhp8Jk,0V81]Eb9S5kMKh-$87gibHN/:)qMFah,8A'mPb`,0KN_&Mt8
+GnQ@%$=+$P"@3g8N`4C#Q~>
+%%EndData
+end restore showpage
+%%Trailer
+%%EOF
diff --git a/systems/doc/metapost/source-tutorial/previewer.pdf b/systems/doc/metapost/source-tutorial/previewer.pdf
new file mode 100644
index 0000000000..e2fea7a7a5
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/previewer.pdf
Binary files differ
diff --git a/systems/doc/metapost/source-tutorial/previewer.png b/systems/doc/metapost/source-tutorial/previewer.png
new file mode 100644
index 0000000000..4bf6fb95f6
--- /dev/null
+++ b/systems/doc/metapost/source-tutorial/previewer.png
Binary files differ