diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /systems/doc/metapost |
Initial commit
Diffstat (limited to 'systems/doc/metapost')
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 Binary files differnew file mode 100644 index 0000000000..4d11331f52 --- /dev/null +++ b/systems/doc/metapost/grdemo-doc.pdf diff --git a/systems/doc/metapost/grdemo.pdf b/systems/doc/metapost/grdemo.pdf Binary files differnew file mode 100644 index 0000000000..faeaa99e6f --- /dev/null +++ b/systems/doc/metapost/grdemo.pdf diff --git a/systems/doc/metapost/mpboxes.pdf b/systems/doc/metapost/mpboxes.pdf Binary files differnew file mode 100644 index 0000000000..dba64f0c39 --- /dev/null +++ b/systems/doc/metapost/mpboxes.pdf diff --git a/systems/doc/metapost/mpgraph.pdf b/systems/doc/metapost/mpgraph.pdf Binary files differnew file mode 100644 index 0000000000..2ec2ac7801 --- /dev/null +++ b/systems/doc/metapost/mpgraph.pdf diff --git a/systems/doc/metapost/mpintro.pdf b/systems/doc/metapost/mpintro.pdf Binary files differnew file mode 100644 index 0000000000..29b6d37175 --- /dev/null +++ b/systems/doc/metapost/mpintro.pdf diff --git a/systems/doc/metapost/mplibapi.pdf b/systems/doc/metapost/mplibapi.pdf Binary files differnew file mode 100644 index 0000000000..de3847e0e5 --- /dev/null +++ b/systems/doc/metapost/mplibapi.pdf diff --git a/systems/doc/metapost/mpman.pdf b/systems/doc/metapost/mpman.pdf Binary files differnew file mode 100644 index 0000000000..16e32d2ca4 --- /dev/null +++ b/systems/doc/metapost/mpman.pdf 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 ¢er point &\\ +n &top center point &\\ +s &bottom center point &\\ +w ¢er left point &\\ +e ¢er right point &\\ +nw &top left corner &\texttt{boxit} only\\ +ne &top right corner &\texttt{boxit} only\\ +sw &bottom left corner &\texttt{boxit} only\\ +se &bottom right corner &\texttt{boxit} only\\ +dx &horizontal clearance &\\ +dy &vertical clearance &\\ +off &actual location of box contents &\\ +\hline +\end{tabular} +\end{table} + +\begin{table}[hp] +\centering +\caption{\strut Internal variables with numeric values} +\label{ivartab} +\index{variables!internal} +\begin{tabular}[t]{|>{\ttfamily}l|r|>{\arraybackslash}p{3.5in}|} +\hline +\multicolumn1{|c}{Name}& \multicolumn1{|c}{Page}& \multicolumn1{|c|}{Explanation}\\ +\hline +\hline +circmargin\index{circmargin?\texttt{circmargin}}& \pageref{Dcmargin}& + clearance around contents of a circular or oval box\\\hline +defaultdx\index{defaultdx?\texttt{defaultdx}}& \pageref{Ddefaultdx}& + usual horizontal space around box contents (default 3{\tt bp})\\\hline +defaultdy\index{defaultdy?\texttt{defaultdy}}& \pageref{Ddefaultdy}& + usual vertical space around box contents (default 3{\tt bp})\\\hline +\end{tabular} +\end{table} + + +\bibliographystyle{plain} +\bibliography{mpboxes} + +\printindex + +\end{document} + + + +% Copyright 1990 - 1995 by AT&T Bell Laboratories. + +% Permission to use, copy, modify, and distribute this software +% and its documentation for any purpose and without fee is hereby +% granted, provided that the above copyright notice appear in all +% copies and that both that the copyright notice and this +% permission notice and warranty disclaimer appear in supporting +% documentation, and that the names of AT&T Bell Laboratories or +% any of its entities not be used in advertising or publicity +% pertaining to distribution of the software without specific, +% written prior permission. + +% AT&T disclaims all warranties with regard to this software, +% including all implied warranties of merchantability and fitness. +% In no event shall AT&T be liable for any special, indirect or +% consequential damages or any damages whatsoever resulting from +% loss of use, data or profits, whether in an action of contract, +% negligence or other tortious action, arising out of or in +% connection with the use or performance of this software. + +% In addition, John Hobby, the original author of MetaPost and this +% manual, makes the following requests: +% - I request that it remain clear that I am the author of +% "A User's Manual for MetaPost" and "Drawing Graphs with MetaPost". +% - I request to be consulted before significant changes are made. + +%%% Local Variables: +%%% mode: latex +%%% TeX-PDF-mode: t +%%% TeX-master: t +%%% End: diff --git a/systems/doc/metapost/source-manual/mpgraph.bib b/systems/doc/metapost/source-manual/mpgraph.bib new file mode 100644 index 0000000000..27ef07de1f --- /dev/null +++ b/systems/doc/metapost/source-manual/mpgraph.bib @@ -0,0 +1,98 @@ +% BibTeX entries for MetaPost doc, by John Hobby. Public domain. + +@string{jcompstatg = {Journal of Computational and Statistical Graphics}} + +@incollection{BenKer90, + author = "Jon L. Bentley and Brian W. Kernighan", + title = "Grap---A language for Typesetting Graphs", + booktitle = "Unix Research System Papers", + publisher = "{AT\&T} Bell Laboratories", + address = "Murray Hill, New Jersey", + edition = "Tenth", + volume = "{II}", + pages = "109--146", + year = 1990 +} +@book{Cleve85, + author = "William S. Cleveland", + title = "The Elements of Graphing Data", + publisher = "Hobart Press", + address = "Summit, New Jersey", + year = "1985, revised 1994" +} +@book{Cleve93, + author = "Cleveland, William S.", + title = "Visualizing Data", + publisher = "Hobart Press", + address = "Summit, New Jersey", + year= 1993, +} +@book{Tufte83, + author = "Edward R. Tufte", + title = "Visual Display of Quantitative Information", + publisher = "Graphics Press", + address = "Box 430, Cheshire, Connecticut 06410", + year = 1983 +} +@article{Cleve93a, + author = "Cleveland, William S.", + title = "A Model for Studying Display Methods of Statistical + Graphics (with discussion)", + journal = jcompstatg, + year = "to appear", + volume = 3 +} +@book{Census92, + author = "U.S. Bureau of the Census", + title = "Statistical Abstracts of the United States: 1992", + edition = "112th", + address = "Washington, D.C.", + year = 1992 +} +@book{LaTeXman, + author = "Leslie Lamport", + title = "{\LaTeX}: A Document Preparation System", + publisher = "Addison Wesley", + address = "Reading, Massachusetts", + year = 1986 +} +@book{ad:red, + author = "Adobe Systems Inc.", + title = "{P}ost{S}cript Language Reference Manual", + publisher = "Addison Wesley", + address = "Reading, Massachusetts", + edition = "second", + year = 1990 +} + +@inproceedings{ho:mp4, + author = "John D. Hobby", + title = "Introduction to {MetaPost}", + booktitle = "Euro{\TeX} '92 Proceedings", + month = sep, + year = 1992, + pages = "21--36" +} +[An updated version appeared in the April 1999 Issue of "Eutupon", + the news lettter for the Greek TeX friends group. +] + +@techreport{ho:mp3, + title = "A User's manual for {MetaPost}", + author = "John D. Hobby", + institution = "AT\&T Bell Laboratories", + address = "Murray Hill, New Jersey", + type = "Computing Science Technical Report", + number = "no.~162", + note = {Available as http://cm.bell-labs.com/cs/cstr/162.ps.gz}, + month = apr, + year = 1992 +} +@book{kn:d, + author = "Donald E. Knuth", + note = "Volume D of {\it Computers and Typesetting}", + title = "{\MF} the Program", + publisher = "Addison Wesley", + address = "Reading, Massachusetts", + year = 1986 +} diff --git a/systems/doc/metapost/source-manual/mpgraph.mp b/systems/doc/metapost/source-manual/mpgraph.mp new file mode 100644 index 0000000000..2c94edfe54 --- /dev/null +++ b/systems/doc/metapost/source-manual/mpgraph.mp @@ -0,0 +1,141 @@ +% Figures for MetaPost doc, by John Hobby. Public domain. + +input graph + +if scantokens(mpversion) < 1.200: + filenametemplate +else: + outputtemplate := +fi +"%j-%c.mps"; + +%if false: %% Begin skipping already debugged figures +%fi input sarith %% End skipping of already debugged figures + +beginfig(1); +draw begingraph(3in,2in); + gdraw "agepop91.d"; + endgraph; +endfig; + + +beginfig(2); +draw begingraph(3in,2in); + gdraw "agepop91.d" plot btex$\bullet$etex; + endgraph; +endfig; + + +beginfig(3); +draw begingraph(3in,2in); + glabel.lft(btex \vbox{\hbox{Population} \hbox{in millions}} etex, OUT); + glabel.bot(btex Age in years etex, OUT); + gdraw "agepopm.d"; + endgraph; +endfig; + + +beginfig(4); +draw begingraph(3in,2in); + glabel.lft(btex \vbox{\hbox{Population} \hbox{in millions}} etex, OUT); + glabel.bot(btex Age in years etex, OUT); + setrange(origin, whatever,whatever); + gdraw "agepopm.d"; + endgraph; +endfig; + + +beginfig(5); +draw begingraph(2.3in,2in); + setcoords(log,log); + glabel.lft(btex Seconds etex,OUT); + glabel.bot(btex Matrix size etex, + OUT); + gdraw "matmul.d" dashed evenly; + glabel.ulft(btex Standard etex,8); + gdraw "matmul.d"; + glabel.lrt(btex Strassen etex,7); + endgraph; +endfig; + + +beginfig(6); +draw begingraph(6.5cm,4.5cm); + setrange(80,0, 90,whatever); + glabel.bot(btex Year etex, OUT); + glabel.lft(btex \vbox{\hbox{Emissions in} \hbox{thousands of} + \hbox{metric tons} \hbox{(heavy line)}}etex, OUT); + gdraw "lead.d" withpen pencircle scaled 1.5pt; + autogrid(,otick.lft); + setcoords(linear,linear); + setrange(80,0, 90,whatever); + glabel.rt(btex \vbox{\hbox{Micrograms} \hbox{per cubic} + \hbox{meter of air} \hbox{(thin line)}}etex, OUT); + gdraw "lead.d"; + autogrid(otick.bot,otick.rt); + endgraph; +endfig; + + +input sarith + +beginfig(7); +vardef newy(expr y) = (256/75)*y + mlog y enddef; +draw begingraph(3in,2in); + glabel.lft(btex \vbox{\hbox{Population} \hbox{in millions}} etex, OUT); + path p; + gdata("timepop.d", $, augment.p($1, newy(Scvnum $2)); ); + gdraw p withpen nullpen; + for y=5,10,20,50,100,150,200,250: + grid.lft(format("%g",y), newy(y)) withcolor .85white; + endfor + autogrid(grid.bot,) withcolor .85white; + gdraw p; + frame.llft; + endgraph; +endfig; + +beginfig(8); +defaultfont:="cmr7"; +draw begingraph(3in,2in); + glabel.lft(btex \vbox{\hbox{Life}\hbox{expectancy}} etex, OUT); + glabel.bot(btex Per capita G.N.P. (thousands of dollars) etex, OUT); + setcoords(log,linear); + gdata("countries.d", s, + glabel(s3, s1, s2); + ) + endgraph; +endfig; + + +beginfig(9); +draw begingraph(3in,2in); + glabel.lft(btex \vbox{\hbox{Quadrillions}\hbox{of BTU}} etex, OUT); + path p[]; + numeric t; + gdata("energy.d", $, + t:=0; augment.p1($1,0); + for j=2 upto 5: + t:=t+scantokens $[j]; augment.p[j]($1,t); + endfor) + picture lab[]; + lab2=btex coal etex; lab3=btex crude oil etex; + lab4=btex natural gas etex; lab5=btex hydroelectric etex; + for j=5 downto 2: + gfill p[j]--reverse p[j-1]--cycle withcolor .16j*white; + glabel.lft(image(unfill bbox lab[j]; draw lab[j]), .7+length p[j]); + endfor + endgraph; +endfig; + + +beginfig(10); +draw format("%g",2+2); +endfig; + +beginfig(11); +draw format("%3g","6.022e23"); +endfig; + + +end diff --git a/systems/doc/metapost/source-manual/mpgraph.tex b/systems/doc/metapost/source-manual/mpgraph.tex new file mode 100644 index 0000000000..759c6e8506 --- /dev/null +++ b/systems/doc/metapost/source-manual/mpgraph.tex @@ -0,0 +1,1044 @@ +% $Id: mpgraph.tex 870 2009-03-06 11:04:56Z stephanhennig $ +% MetaPost graph doc, by John Hobby. License at end. +\listfiles +\RequirePackage{ifpdf} +\ifpdf +\ifnum\pdftexversion<140 +\else +\pdfminorversion=5 +\pdfobjcompresslevel=1% Use compressed object streams. +\fi +\RequirePackage{cmap} +\fi +\documentclass{article} % article is NOT the original style +\usepackage[T1]{fontenc} +\usepackage{lmodern} +\usepackage{textcomp} +\usepackage{mflogo} +\usepackage{makeidx} +\usepackage{fancyvrb} +\usepackage{ctabbing} +\RecustomVerbatimEnvironment{verbatim}{BVerbatim}{baseline=c} +\usepackage{graphics} +\usepackage[textwidth=6in,textheight=8.65in]{geometry} +\usepackage{multicol} + +\newcommand\descr[1]{{\langle\hbox{\rm#1}\rangle}} +\newcommand\invisgap{\nobreak\hskip0pt\relax} +\newcommand\tdescr[1]{$\langle$\invisgap{\rm#1}\invisgap$\rangle$} +\newcommand\Ignore[1]{} % For fooling delatex so spell will work + +\newcommand\mathcenter[1]{\vcenter{\hbox{#1}}} + +\author{John D. Hobby} +\title{Drawing Graphs with {MetaPost}} +\date{} + + +\newcommand\myabstract{% +This paper describes a graph-drawing package that has been implemented +as an extension to the MetaPost graphics language. MetaPost has +a powerful macro facility for implementing such extensions. There are +also some new language features that support the graph macros. +Existing features for generating and manipulating pictures +allow the user to do things that would be difficult to achieve +in a stand-alone graph package.} + +\newcommand\mykeywords{% + typesetting; graphs; MetaPost} + +\usepackage[rgb,x11names]{xcolor}% Optimize for screen reading. +\usepackage{hyperxmp} +\usepackage{hyperref} +\hypersetup{ + pdftitle={Drawing Graphs with MetaPost}, + pdfauthor={John D. Hobby and the MetaPost development team}, + pdfkeywords={typesetting, graphs, MetaPost, TeX} +} +\hypersetup{ + pdfstartview={XYZ null null null},% Zoom factor is determined by viewer. + colorlinks, + linkcolor=RoyalBlue3, + urlcolor=Chocolate4, + citecolor=SpringGreen3 +} +\usepackage[all]{hypcap} +\ifpdf +\pdfmapfile{=cm2lm.map}% replace CM by LM in figures +\else +\DeclareGraphicsExtensions{.mps} +\DeclareGraphicsRule{mps}{eps}{*}{} +\usepackage{breakurl} +\fi + + +\begin{document} + \maketitle + \begin{abstract} \myabstract \end{abstract} + \ifx\keywords\undefined \else + \begin{keywords} \mykeywords \end{keywords} + \fi + +\setlength{\columnsep}{2.5em} +\begin{multicols}{2} +\tableofcontents +\end{multicols} + +\section{Introduction} +\label{intro} + +MetaPost is a batch-oriented graphics language based on Knuth's \MF\footnote{\MF\ +is a trademark of Addison Wesley Publishing Company.}, but with +PostScript\footnote{PostScript is a registered trademark of Adobe Systems Inc.} +output and numerous features for integrating text and graphics. +The author has tried to make this paper as independent as possible of the +user's manual~\cite{ho:mp3}, but fully appreciating all the material requires +some knowledge of the MetaPost language. + +We concentrate on the mechanics of producing particular kinds of graphs +because the question of what type of graph is best in a given situation +is covered elsewhere; e.g., Cleveland~\cite{Cleve85,Cleve93,Cleve93a} and +Tufte~\cite{Tufte83}. +The goal is to provide at least the power of UNIX\footnote{UNIX is a registered +trademark of UNIX System Laboratories, Inc.} {\it +grap\/}~\cite{BenKer90}, but within the MetaPost language. +Hence the package is implemented using MetaPost's powerful macro facility. + +The graph macros provide the following functionality: +\begin{enumerate} +\item Automatic scaling +\item Automatic generation and labeling of tick marks or grid lines +\item Multiple coordinate systems +\item Linear and logarithmic scales +\item Separate data files +\item Ability to handle numbers outside the usual range +\item Arbitrary plotting symbols +\item Drawing, filling, and labeling commands for graphs +\end{enumerate} +In addition to these items, the user also has access to all the features +described in the MetaPost user's manual~\cite{ho:mp3}. +These include access to almost all the features of PostScript, +ability to use and manipulate typeset text, +ability to solve linear equations, +and data types for points, curves, pictures, and coordinate transformations. + +Section~\ref{grmac} describes the graph macros from a user's perspective +and presents several examples. Sections \ref{nummac} and~\ref{formsec} discuss +auxiliary packages for manipulating and typesetting numbers and Section~\ref{concl} +gives some concluding remarks. Appendix~\ref{summsec} summarizes the graph-drawing +macros. + + +\section{Using the Graph Macros} +\label{grmac} + +A MetaPost input file that uses the graph macros should begin with +$$ \hbox{\tt input graph} $$ +This reads a macro file {\tt graph.mp} and defines the graph-drawing commands +explained below. The rest of the file should be one or more instances of +$$ \vbox{\hbox{\tt beginfig($\descr{figure number}$);} + \hbox{\tt $\descr{graphics commands}$ endfig;}} +$$ +followed by {\tt end}. + +The following \tdescr{graphics commands} suffice to generate the graph in +Figure~\ref{fig1} from the data file {\tt agepop91.d}: +$$\begin{verbatim} +draw begingraph(3in,2in); + gdraw "agepop91.d"; + endgraph; +\end{verbatim} +$$ +(Each line of {\tt agepop91.d} gives an age followed the estimated number of +Americans of that age in 1991 \cite{Census92}.) + +\begin{figure}[htp] +$$ \includegraphics{mpgraph-1.mps} $$ +\caption{A graph of the 1991 age distribution in the United States} +\label{fig1} +\end{figure} + +\subsection{Basic Graph-Drawing Commands} + +% begingraph, endgraph, gdraw + +All graphs should begin with +$$ \hbox{\tt begingraph($\descr{width}$,$\descr{height}$);} $$ +and end with {\tt endgraph}. This is syntactically a \tdescr{picture expression}, +so it should be preceded by {\tt draw} and followed by a semicolon as in the +example.\footnote{See the User's Manual~\cite{ho:mp3} for explanations of {\tt draw} +commands and syntactic elements like \tdescr{picture expression}.} +The \tdescr{width} and \tdescr{height} give the dimensions of the +graph itself without the axis labels. + +The command +$$ {\tt gdraw}\ \descr{expression}\ \descr{option list} $$ +draws a graph line. If the \tdescr{expression} is of type string, it names a data +file; otherwise it is a path that gives the function to draw. The +\tdescr{option list} is zero or more drawing options +$$ {\tt withpen} \descr{pen expression} + \mid {\tt withcolor} \descr{color expression} + \mid {\tt dashed} \descr{picture expression} +$$ +that give the line width, color, or dash pattern as explained in the User's +Manual~\cite{ho:mp3}. + +% plot <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 Binary files differnew file mode 100644 index 0000000000..e2fea7a7a5 --- /dev/null +++ b/systems/doc/metapost/source-tutorial/previewer.pdf diff --git a/systems/doc/metapost/source-tutorial/previewer.png b/systems/doc/metapost/source-tutorial/previewer.png Binary files differnew file mode 100644 index 0000000000..4bf6fb95f6 --- /dev/null +++ b/systems/doc/metapost/source-tutorial/previewer.png |