summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/metapost
diff options
context:
space:
mode:
authorTaco Hoekwater <taco@elvenkind.com>2011-04-05 14:13:11 +0000
committerTaco Hoekwater <taco@elvenkind.com>2011-04-05 14:13:11 +0000
commit3bd11c5b320d265b89c965f63f57018ef818b876 (patch)
tree67308b260935e36efaaf028ea64d7b8568530563 /Master/texmf-dist/doc/metapost
parentdce9945ab7f97cdf0849484839de601a8e959d39 (diff)
Update to metapost 1.503
git-svn-id: svn://tug.org/texlive/trunk@21975 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/metapost')
-rw-r--r--Master/texmf-dist/doc/metapost/base/mpboxes.pdfbin371620 -> 371601 bytes
-rw-r--r--Master/texmf-dist/doc/metapost/base/mpgraph.pdfbin467533 -> 467471 bytes
-rw-r--r--Master/texmf-dist/doc/metapost/base/mpintro.pdfbin234860 -> 234688 bytes
-rw-r--r--Master/texmf-dist/doc/metapost/base/mplibapi.pdfbin0 -> 243123 bytes
-rw-r--r--Master/texmf-dist/doc/metapost/base/mpman.pdfbin858284 -> 895061 bytes
-rw-r--r--Master/texmf-dist/doc/metapost/base/source-manual/Makefile30
-rw-r--r--Master/texmf-dist/doc/metapost/base/source-manual/README6
-rw-r--r--Master/texmf-dist/doc/metapost/base/source-manual/TODO41
-rw-r--r--Master/texmf-dist/doc/metapost/base/source-manual/charts.mp120
-rw-r--r--Master/texmf-dist/doc/metapost/base/source-manual/mp.1289
-rw-r--r--Master/texmf-dist/doc/metapost/base/source-manual/mpboxes.bib1
-rw-r--r--Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-legacy.tex686
-rw-r--r--Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-optab.tex10
-rw-r--r--Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-refman.tex351
-rw-r--r--Master/texmf-dist/doc/metapost/base/source-manual/mpman-charts.mp210
-rw-r--r--Master/texmf-dist/doc/metapost/base/source-manual/mpman.bib19
-rw-r--r--Master/texmf-dist/doc/metapost/base/source-manual/mpman.mp48
-rw-r--r--Master/texmf-dist/doc/metapost/base/source-manual/mpman.tex1363
18 files changed, 1894 insertions, 1280 deletions
diff --git a/Master/texmf-dist/doc/metapost/base/mpboxes.pdf b/Master/texmf-dist/doc/metapost/base/mpboxes.pdf
index 3a0182c4e20..f06e8847a64 100644
--- a/Master/texmf-dist/doc/metapost/base/mpboxes.pdf
+++ b/Master/texmf-dist/doc/metapost/base/mpboxes.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/metapost/base/mpgraph.pdf b/Master/texmf-dist/doc/metapost/base/mpgraph.pdf
index d49c39a1dcd..b8d5591247f 100644
--- a/Master/texmf-dist/doc/metapost/base/mpgraph.pdf
+++ b/Master/texmf-dist/doc/metapost/base/mpgraph.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/metapost/base/mpintro.pdf b/Master/texmf-dist/doc/metapost/base/mpintro.pdf
index e845c115287..534f2891b67 100644
--- a/Master/texmf-dist/doc/metapost/base/mpintro.pdf
+++ b/Master/texmf-dist/doc/metapost/base/mpintro.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/metapost/base/mplibapi.pdf b/Master/texmf-dist/doc/metapost/base/mplibapi.pdf
new file mode 100644
index 00000000000..d9b491c144a
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/mplibapi.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/metapost/base/mpman.pdf b/Master/texmf-dist/doc/metapost/base/mpman.pdf
index 1e2e4bef1e6..4e7fa152f66 100644
--- a/Master/texmf-dist/doc/metapost/base/mpman.pdf
+++ b/Master/texmf-dist/doc/metapost/base/mpman.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/Makefile b/Master/texmf-dist/doc/metapost/base/source-manual/Makefile
index 21eaebfcf74..de95dc82304 100644
--- a/Master/texmf-dist/doc/metapost/base/source-manual/Makefile
+++ b/Master/texmf-dist/doc/metapost/base/source-manual/Makefile
@@ -2,16 +2,24 @@
# 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
-ps: mpman.ps mpgraph.ps mpboxes.ps
+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
@@ -28,8 +36,9 @@ mpgraph.pdf: mpgraph.tex mpgraph.bib mpgraph.mp
$(pdflatex) mpgraph
$(pdflatex) mpgraph
-mpman.pdf: mpman.tex mpman-app-legacy.tex mpman-app-optab.tex mpman-app-refman.tex mpman.bib mpman.ist mpman.mp
+mpman.pdf: 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
$(pdflatex) mpman
$(bibtex) mpman
$(pdflatex) mpman
@@ -37,6 +46,12 @@ mpman.pdf: mpman.tex mpman-app-legacy.tex mpman-app-optab.tex mpman-app-refman.t
$(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
@@ -55,8 +70,9 @@ mpgraph.ps: mpgraph.tex mpgraph.bib mpgraph.mp
$(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
+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
@@ -66,8 +82,8 @@ mpman.ps: mpman.tex mpman-app-legacy.tex mpman-app-optab.tex mpman-app-refman.te
$(dvips) mpman
clean:
- rm -f *.aux *.bbl *.blg *.dvi *.log *.mpx *.mps
- rm -f *.idx *.ilg *.ind *.toc *.out
+ $(RM) *.aux *.bbl *.blg *.dvi *.idx *.ilg *.ind *.log *.mps *.mpx *.out *.toc mpxerr.*
+ $(RM) *.tui *.tuo *.tmp *-mpgraph.mp
distclean: clean
- rm -f mp*.pdf mp*.ps
+ $(RM) mp*.pdf mp*.ps
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/README b/Master/texmf-dist/doc/metapost/base/source-manual/README
index 61cdd102fc8..bbff9fb2c19 100644
--- a/Master/texmf-dist/doc/metapost/base/source-manual/README
+++ b/Master/texmf-dist/doc/metapost/base/source-manual/README
@@ -24,6 +24,7 @@ README
TODO
agepop91.d
agepopm.d
+charts.mp
cm2lm.map
countries.d
ctabbing.sty
@@ -50,7 +51,10 @@ mpgraph.tex
mpintro.bib
mpintro.mp
mpintro.tex
-mpman-optab.tex
+mpman-app-legacy.tex
+mpman-app-optab.tex
+mpman-app-refman.tex
+mpman-charts.mp
mpman.bib
mpman.ist
mpman.mp
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/TODO b/Master/texmf-dist/doc/metapost/base/source-manual/TODO
index 4aea80f9d41..618b973ebdd 100644
--- a/Master/texmf-dist/doc/metapost/base/source-manual/TODO
+++ b/Master/texmf-dist/doc/metapost/base/source-manual/TODO
@@ -31,10 +31,8 @@ mp-implementors list or alternatively the metapost list.
*** Wanted For Release ***
*****************************
-mpman.tex
-* Describe environment variables.
-* Add note on postcontrol and precontrol when discussing control points.
-* Add description of interaction mode commands.
+Notes on the MetaPost Workflow:
+* (SH) Describe variables jobname, charcode.
@@ -43,19 +41,34 @@ mpman.tex
*** Mid Term Issues ***
*****************************
+Introduction:
* Revise introduction.
-* Move prologues discussion to section 3.
+
+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.
* (SH) Revise (and add more) flow charts for MetaPost workflow.
-* Information on using MetaPost from within LaTeX (emp), ConTeXt
- and LuaTeX.
+* 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).
-* Add a sub-section discussing colours in section 9.
-* (SH) Colour cars and change code example in section 9.9.
-* Describe mpware in section "Legacy information".
+* Fix bad description of prologues in table ivartab.
+* Move discussion of prologues to sec. workflow2?
+
+Advanced Graphics:
+* Add a sub-section discussing colours.
+* (SH) Colour cars and change code example in section piccomp.
+
+Reference Manual:
+* Describe environment variables and configuration files.
+* Describe missing variables, constants, and operators.
+* Add description of interaction mode.
+
+Legacy Information:
+* Cite original Hobby papers.
+* Describe mpware (currently scattered around in mpman).
@@ -64,14 +77,18 @@ mpman.tex
*** 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/Master/texmf-dist/doc/metapost/base/source-manual/charts.mp b/Master/texmf-dist/doc/metapost/base/source-manual/charts.mp
new file mode 100644
index 00000000000..f7ba689a509
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/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/Master/texmf-dist/doc/metapost/base/source-manual/mp.1 b/Master/texmf-dist/doc/metapost/base/source-manual/mp.1
deleted file mode 100644
index 76df137ca79..00000000000
--- a/Master/texmf-dist/doc/metapost/base/source-manual/mp.1
+++ /dev/null
@@ -1,289 +0,0 @@
-.\" MetaPost man page, by John Hobby. Public domain.
-.TH MP 1
-.CT 1 writing_other
-.SH NAME
-mp, MetaPost \- system for drawing pictures
-.SH SYNOPSIS
-.B mp
-[
-.B -I
-]
-[
-.B -T
-]
-[
-.I first-line
-]
-.SH DESCRIPTION
-.I Mp
-interprets the MetaPost language and produces
-.I PostScript
-pictures. The MetaPost language is similar to Knuth's
-.I METAFONT
-with additional features for including
-.IR tex (1)
-or
-.IR troff (1)
-commands and accessing features of PostScript not found in METAFONT.
-The
-.B -T
-flag selects
-.I troff
-instead of
-.IR tex .
-.PP
-An argument given on the command line
-behaves as the first input line.
-That can be either a (possibly truncated) file name
-or a sequence MetaPost commands starting with
-.L \e
-and including an
-.L input
-command. Thus
-.L mp figs
-processes the file
-.LR figs.mp .
-The basename of
-.L figs
-becomes the
-.IR jobname ,
-and is used in forming output file names. If no file is named, the
-jobname becomes
-.LR mpout .
-The default
-.L .mp
-extension can be overridden by specifying an extension explicitly.
-.PP
-There is normally one output file for each picture generated,
-and the output files are named
-.IR jobname.nnn ,
-where
-.I nnn
-is a number passed to the
-.L beginfig
-macro. The output file name
-can also be
-.IB jobname .ps
-if this number is negative.
-.PP
-The output files can be used as figures in a TeX document by including
-.ce
-.BI "\especial{psfile=" jobname.nnn }
-in the TeX document. Alternatively, one can
-.L \einput epsf.tex
-and then use the macro
-.BI "\eepsfbox{" jobname.nnn }
-to produce a box of the appropriate size containing the figure.
-.TP
-.BI btex " TeX commands " etex
-This causes
-.I mp
-to generate a MetaPost picture expression that corresponds to the
-TeX commands. If the TeX commands generate
-more than one line of text, it must be in a
-.L \evbox
-or a minipage environment.
-.TP
-.BI verbatimtex " TeX commands " etex
-This is ignored by
-.I mp
-except that the TeX commands are passed on to TeX. When using LaTeX
-instead of TeX the input file must start with a
-.L verbatimtex
-block that gives the
-.L \edocumentstyle
-and
-.L "\ebegin{document}"
-commands.
-.PP
-Since most TeX fonts have to be downloaded as bitmaps, the
-.L btex
-feature works best when the output of
-.L mp
-is to be included in a TeX document so that
-.IR dvips (1)
-can download the fonts. For self-contained PostScript output that can be
-used directly or included in a
-.I troff
-document, start your MetaPost input file with the command
-.L "prologues:=1"
-and stick to standard PostScript fonts. TeX and MetaPost use the names in the
-third column of the file
-.LR /usr/lib/mp/trfonts.map .
-.PP
-MetaPost output can be included in a
-.I troff
-document via the
-.L "-mpictures"
-macro package. In this case
-.I mp
-should be invoked with the
-.B -T
-flag so that the commands between
-.L btex
-and
-.L etex
-or between
-.L verbatimtex
-and
-.L etex
-are interpreted as
-.I troff
-instead of TeX. (This automatically sets
-.L prologues:=1
-).
-.PP
-Here is a list of the environment variables affect the behavior of
-.IR mp :
-.TF MPXCOMMAND
-.TP
-.B MPINPUTS
-Search path for
-.L \einput
-files.
-It should be colon-separated,
-and start with dot.
-Default:
-.L .:/usr/lib/mp
-.TP
-.B MFINPUTS
-Auxiliary search path for
-.L \einput
-files with
-.L .mf
-extensions.
-.TP
-.B TEXFONTS
-Search path for font metric files.
-.TP
-.B MPXCOMMAND
-The name of a shell script that converts embedded typesetting commands
-to a form that
-.I mp
-understands.
-Defaults:
-.L /usr/lib/mp/bin/makempx
-for
-.I tex
-and
-.L /usr/lib/mp/bin/troffmpx
-for
-.I troff
-.TP
-.B TEX
-The version of TeX to use when processing
-.L btex
-and
-.L verbatimtex
-commands. Default:
-.L tex
-.TP
-.B TROFF
-The
-.I troff
-pipeline for
-.L btex
-and
-.L verbatimtex
-commands. Default:
-.L eqn -d\e$\e$ | troff
-.TP
-.B MPMEMS
-Search path for
-.L .mem
-files. Default:
-.L .:/usr/lib/mp
-.TP
-.B MPPOOL
-Search path for strings.
-Default:
-.L .:/usr/lib/mp
-.TP
-.B MPEDITOR
-A command for invoking an editor with
-.L %s
-in place of the file name and
-.L %d
-in place of the line number.
-.TP
-.B TEXVFONTS
-Search path for virtual fonts.
-.TP
-.B MPTEXPRE
-Name of a file that is prepended before running tex.
-If this file exists,
-.I mp
-behaves as if the file were inside of a
-.L verbatimtex
-block at the beginning of each input file. Default:
-.L mptexpre.tex
-.PD
-.PP
-A
-.L .mem
-file is a binary file that permits fast loading of fonts and macro packages.
-.I Mp
-reads the default
-.F plain.mem
-unless another
-.L .mem
-file is specified at the start of the first line with an
-.L &
-just before it. There is also an
-.F mfplain.mem
-that simulates plain METAFONT so that
-.I mp
-can read
-.L .mf
-fonts. (Plain METAFONT is described in
-.I The
-.IR METAFONTbook ).
-.PP
-Experts can create
-.L .mem
-files be invoking
-.I mp
-with the
-.B -I
-switch and giving macro definitions followed by a
-.L dump
-command.
-.PP
-The MetaPost language is similar to METAFONT, but the manual
-.I A User's Manual for MetaPost
-assumes no knowledge of METAFONT. MetaPost does not have bitmap
-output commands or METAFONT's online display mechanism.
-.SH FILES
-.TF /usr/lib/mp/trfonts.map
-.TP
-.F /usr/lib/mp/*
-macros,
-.L .mem
-files, and tables for handling included
-.I tex
-and
-.I troff
-.TP
-.F /usr/lib/mp/bin
-Directory for programs that handle included
-.I tex
-and
-.IR troff .
-.F /usr/lib/mp/trfonts.map
-table of corresponding font names for
-.IR troff ,
-PostScript, and TeX
-.TP
-.F /usr/lib/mp/examples.mp
-The source file for a few sample figures.
-.IR troff .
-.SH "SEE ALSO"
-.IR tex (1),
-.br
-Donald E. Knuth,
-.I The METAFONTbook,
-Addison Wesley, 1986,
-.br
-John D. Hobby,
-.I A User's Manual for MetaPost
-CSTR 162.
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpboxes.bib b/Master/texmf-dist/doc/metapost/base/source-manual/mpboxes.bib
index 6adf4cd1c7a..6b4042b1a8f 100644
--- a/Master/texmf-dist/doc/metapost/base/source-manual/mpboxes.bib
+++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpboxes.bib
@@ -17,4 +17,3 @@
pages = "53--77",
year = 1990
}
-}
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-legacy.tex b/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-legacy.tex
index e73cd05ea45..3af2449244a 100644
--- a/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-legacy.tex
+++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-legacy.tex
@@ -1,343 +1,343 @@
-\svnInfo $Id: mpman-app-legacy.tex 1072 2009-06-01 16:18:44Z 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\\
-outputformat\\
-outputtemplate\\
-pathpart\\
-penpart\\
-prologues\\
-readfrom\\
-redpart\\
-restoreclipcolor\\
-rgbcolor\\
-setbounds\\
-stroked\\
-textpart\\
-textual\\
-tracinglostchars\\
-troffmode\\
-truecorners\\
-ulcorner\\
-urcorner\\
-verbatimtex\\
-withcmykcolor\\
-withcolor\\
-withgreyscale\\
-withoutcolor\\
-withpostscript\\
-withprescript\\
-withrgbcolor\\
-write to\\
-yellowpart
-\end{multicols}
-\end{minipage}\\\hline
-
-Variables and Macros defined only in Plain MetaPost\\\hline
-\begin{minipage}[b]{.75\linewidth}\ttfamily
-\begin{multicols}{3}
-ahangle\\
-ahlength\\
-background\\
-bbox\\
-bboxmargin\\
-beginfig\\
-beveled\\
-black\\
-blue\\
-buildcycle\\
-butt\\
-center\\
-colorpart\\
-cutafter\\
-cutbefore\\
-cuttings\\
-dashpattern\\
-defaultfont\\
-defaultpen\\
-defaultscale\\
-dotlabel\\
-dotlabels\\
-drawarrow\\
-drawdblarrow\\
-drawoptions\\
-endfig\\
-EOF\\
-evenly\\
-extra\_beginfig\\
-extra\_endfig\\
-green\\
-image\\
-label\\
-labeloffset\\
-mitered\\
-red\\
-rounded\\
-squared\\
-thelabel\\
-white
-\end{multicols}
-\end{minipage}\\\hline
-\end{tabular}
-\caption{Macros and internal variables defined in MetaPost but not \MF.}
-\label{mponly}
-\end{table}
-
-Another limitation of the {\tt mfplain} package is that certain internal
-variables from Plain \MF\index{metafont?\MF} cannot be given reasonable
-MetaPost definitions. These include {\tt displaying}, {\tt
-currentwindow}, \verb|screen_rows|, and \verb|screen_cols| which depend
-on \MF's ability to display images on the computer screen. In addition,
-\verb|pixels_per_inch| is irrelevant since MetaPost uses fixed units of
-PostScript\index{PostScript!point}\index{point!PostScript} points.
-
-The reason why some macros and internal variables\index{internal
-variables}\index{variables!internal} are not meaningful in MetaPost is
-that \MF\ primitive commands {\tt cull}, {\tt display}, {\tt
-openwindow}, {\tt numspecial} and {\tt totalweight} are not implemented
-in MetaPost. Also not implemented are a number of internal variables as
-well as the \tdescr{drawing option} {\tt withweight}. Here is a
-complete listing of the internal variables whose primitive meanings in
-\MF\ do not make sense in MetaPost:
-$$\begin{verbatim}
-autorounding fillin proofing tracingpens xoffset
-chardx granularity smoothing turningcheck yoffset
-chardy hppp tracingedges vppp
-\end{verbatim}
-$$
-
-There is also one \MF\ primitive that has a slightly different meaning in
-MetaPost. Both languages allow statements of the
-form\index{special?\texttt{special}}\label{Dspecl}
-$$ {\tt special}\, \descr{string expression} \hbox{\tt;} $$
-but \MF\ copies the string into its ``generic font'' output file, while
-MetaPost interprets the string as a sequence of PostScript\index{PostScript}
-commands that are to be placed at the beginning of the next output file.
-
-In this regard, it is worth mentioning that rules in \TeX\ material
-included via {\tt btex..etex} in MetaPost are rounded to the correct
-number of pixels according to PostScript\index{PostScript!conversion rules}
-conversion rules~\cite{ad:red2}. In \MF, rules are not generated
-directly, but simply included in specials and interpreted later by
-other programs, such as {\tt gftodvi}\index{gftodvi?\ttt{gftodvi}},
-so there is no special conversion.
-
-All the other differences between \MF\ and MetaPost are features found
-only in MetaPost. These are listed in Table~\ref{mponly}. The only
-commands listed in this table that the preceding sections do not discuss
-are
-\verb|extra_beginfig|\index{extra_beginfig?\texttt{extra\_beginfig}}\label{Dxbfig},
-\verb|extra_endfig|\index{extra_endfig?\texttt{extra\_endfig}}\label{Dxefig},
-and {\tt mpxbreak}. The first two are strings that contain extra
-commands to be processed by {\tt
-beginfig}\index{beginfig?\texttt{beginfig}} and {\tt
-endfig}\index{endfig?\texttt{endfig}} just as \verb|extra_beginchar| and
-\verb|extra_endchar| are processed by {\tt beginchar} and {\tt endchar}.
-(The file {\tt boxes.mp}\index{boxes.mp?\texttt{boxes.mp}} uses these
-features).
-
-The other new feature listed in Table~\ref{mponly} not listed in the
-index is {\tt mpxbreak}\index{mpxbreak?\texttt{mpxbreak}}. This is used
-to separate blocks of translated \TeX\index{TeX?\TeX} or
-troff\index{troff} commands in {\tt mpx}\index{mpx file?{\tt mpx}
- file}\index{files!mpx?{\tt mpx}} files. It should be of no concern to
-users since {\tt mpx} files are generated automatically.
-
-\subsection{File name templates}
-\label{Dfilenametemplate}
-
-The output file naming template mechanism introduced in MetaPost
-version~1.000 originally used a primitive called
-\ttindex{filenametemplate}, as opposed to the internal string variable
-\ttt{outputtemplate}\index{outputtemplate?\texttt{outputtemplate}}
-described in section~\ref{Doutputtemplate}. This primitive took a
-string argument with the same syntax as \ttt{outputtemplate}, except
-that it didn't know about the \verb|%{...}| escape sequence for
-evaluating internal variables, e.g.,:
-
-$$\begin{verbatim}
-filenametemplate "%j-%c.mps";
-\end{verbatim}
-$$
-
-The \verb|filenametemplate| primitive has been deprecated since the
-introduction of \verb|outputtemplate| (version~1.200), but is still
-supported. If you happen to need writing future-proof source files,
-that at the same time are backwards compatible to MetaPost versions
-between 1.000 and~1.200, this output filename template declaration might
-help:
-
-$$\begin{verbatim}
-if scantokens(mpversion) < 1.200:
- filenametemplate
-else:
- outputtemplate :=
-fi
-"%j-%c.mps";
-\end{verbatim}
-$$
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-PDF-mode: t
-%%% TeX-master: "mpman"
-%%% End:
+\svnInfo $Id: mpman-app-legacy.tex 1339 2010-08-15 13:17:48Z 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\\
+outputformat\\
+outputtemplate\\
+pathpart\\
+penpart\\
+prologues\\
+readfrom\\
+redpart\\
+restoreclipcolor\\
+rgbcolor\\
+setbounds\\
+stroked\\
+textpart\\
+textual\\
+tracinglostchars\\
+troffmode\\
+truecorners\\
+ulcorner\\
+urcorner\\
+verbatimtex\\
+withcmykcolor\\
+withcolor\\
+withgreyscale\\
+withoutcolor\\
+withpostscript\\
+withprescript\\
+withrgbcolor\\
+write to\\
+yellowpart
+\end{multicols}
+\end{minipage}\\\hline
+
+Variables and Macros defined only in Plain MetaPost\\\hline
+\begin{minipage}[b]{.75\linewidth}\ttfamily
+\begin{multicols}{3}
+ahangle\\
+ahlength\\
+background\\
+bbox\\
+bboxmargin\\
+beginfig\\
+beveled\\
+black\\
+blue\\
+buildcycle\\
+butt\\
+center\\
+colorpart\\
+cutafter\\
+cutbefore\\
+cuttings\\
+dashpattern\\
+defaultfont\\
+defaultpen\\
+defaultscale\\
+dotlabel\\
+dotlabels\\
+drawarrow\\
+drawdblarrow\\
+drawoptions\\
+endfig\\
+EOF\\
+evenly\\
+extra\_beginfig\\
+extra\_endfig\\
+green\\
+image\\
+label\\
+labeloffset\\
+mitered\\
+red\\
+rounded\\
+squared\\
+thelabel\\
+white
+\end{multicols}
+\end{minipage}\\\hline
+\end{tabular}
+\caption{Macros and internal variables defined in MetaPost but not \MF.}
+\label{mponly}
+\end{table}
+
+Another limitation of the {\tt mfplain} package is that certain internal
+variables from Plain \MF\index{metafont?\MF} cannot be given reasonable
+MetaPost definitions. These include {\tt displaying}, {\tt
+currentwindow}, \verb|screen_rows|, and \verb|screen_cols| which depend
+on \MF's ability to display images on the computer screen. In addition,
+\verb|pixels_per_inch| is irrelevant since MetaPost uses fixed units of
+PostScript\index{PostScript!point}\index{point!PostScript} points.
+
+The reason why some macros and internal variables\index{internal
+variables}\index{variables!internal} are not meaningful in MetaPost is
+that \MF\ primitive commands {\tt cull}, {\tt display}, {\tt
+openwindow}, {\tt numspecial} and {\tt totalweight} are not implemented
+in MetaPost. Also not implemented are a number of internal variables as
+well as the \tdescr{drawing option} {\tt withweight}. Here is a
+complete listing of the internal variables whose primitive meanings in
+\MF\ do not make sense in MetaPost:
+$$\begin{verbatim}
+autorounding fillin proofing tracingpens xoffset
+chardx granularity smoothing turningcheck yoffset
+chardy hppp tracingedges vppp
+\end{verbatim}
+$$
+
+There is also one \MF\ primitive that has a slightly different meaning in
+MetaPost. Both languages allow statements of the
+form\index{special?\texttt{special}}\label{Dspecl}
+$$ {\tt special}\, \descr{string expression} \hbox{\tt;} $$
+but \MF\ copies the string into its ``generic font'' output file, while
+MetaPost interprets the string as a sequence of PostScript\index{PostScript}
+commands that are to be placed at the beginning of the next output file.
+
+In this regard, it is worth mentioning that rules in \TeX\ material
+included via {\tt btex..etex} in MetaPost are rounded to the correct
+number of pixels according to PostScript\index{PostScript!conversion rules}
+conversion rules~\cite{ad:red2}. In \MF, rules are not generated
+directly, but simply included in specials and interpreted later by
+other programs, such as {\tt gftodvi}\index{gftodvi?\ttt{gftodvi}},
+so there is no special conversion.
+
+All the other differences between \MF\ and MetaPost are features found
+only in MetaPost. These are listed in Table~\ref{mponly}. The only
+commands listed in this table that the preceding sections do not discuss
+are
+\verb|extra_beginfig|\index{extra_beginfig?\texttt{extra\_beginfig}}\label{Dxbfig},
+\verb|extra_endfig|\index{extra_endfig?\texttt{extra\_endfig}}\label{Dxefig},
+and {\tt mpxbreak}. The first two are strings that contain extra
+commands to be processed by {\tt
+beginfig}\index{beginfig?\texttt{beginfig}} and {\tt
+endfig}\index{endfig?\texttt{endfig}} just as \verb|extra_beginchar| and
+\verb|extra_endchar| are processed by {\tt beginchar} and {\tt endchar}.
+(The file {\tt boxes.mp}\index{boxes.mp?\texttt{boxes.mp}} uses these
+features).
+
+The other new feature listed in Table~\ref{mponly} not listed in the
+index is {\tt mpxbreak}\index{mpxbreak?\texttt{mpxbreak}}. This is used
+to separate blocks of translated \TeX\index{TeX?\TeX} or
+troff\index{troff} commands in {\tt mpx}\index{mpx file?{\tt mpx}
+ file}\index{files!mpx?{\tt mpx}} files. It should be of no concern to
+users since {\tt mpx} files are generated automatically.
+
+\subsection{File Name Templates}
+\label{Dfilenametemplate}
+
+The output file naming template mechanism introduced in MetaPost
+version~1.000 originally used a primitive called
+\ttindex{filenametemplate}, as opposed to the internal string variable
+\ttt{outputtemplate}\index{outputtemplate?\texttt{outputtemplate}}
+described in section~\ref{Doutputtemplate}. This primitive took a
+string argument with the same syntax as \ttt{outputtemplate}, except
+that it didn't know about the \verb|%{...}| escape sequence for
+evaluating internal variables, e.g.,:
+
+$$\begin{verbatim}
+filenametemplate "%j-%c.mps";
+\end{verbatim}
+$$
+
+The \verb|filenametemplate| primitive has been deprecated since the
+introduction of \verb|outputtemplate| (version~1.200), but is still
+supported. If you happen to need writing future-proof source files,
+that at the same time are backwards compatible to MetaPost versions
+between 1.000 and~1.200, this output filename template declaration might
+help:
+
+$$\begin{verbatim}
+if scantokens(mpversion) < 1.200:
+ filenametemplate
+else:
+ outputtemplate :=
+fi
+"%j-%c.mps";
+\end{verbatim}
+$$
+
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-PDF-mode: t
+%%% TeX-master: "mpman"
+%%% End:
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-optab.tex b/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-optab.tex
index 167e366f611..079ae983e5d 100644
--- a/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-optab.tex
+++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-optab.tex
@@ -1,4 +1,4 @@
-\svnInfo $Id: mpman-app-optab.tex 1072 2009-06-01 16:18:44Z stephanhennig $
+\svnInfo $Id: mpman-app-optab.tex 1416 2010-10-18 06:39:23Z taco $
%%% Two notes on column specification:
%%% (i) Column widths are manually chosen as small as possible to allow
%%% for a wider last X column.
@@ -66,7 +66,7 @@ decimal\index{decimal?\texttt{decimal}}& --& numeric& string& \pageref{Ddeco
\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
+\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
@@ -105,14 +105,14 @@ penoffset of\index{penoffset of?\texttt{penoffset of}}& pair& pen& pair& --&
penpart\index{penpart?\texttt{penpart}}& --& picture& pen& \pageref{Dpenpart}& Pen of a stroked picture component\\\hline
picture\index{picture?\texttt{picture}}& --& any& boolean& \pageref{Dpictop}& Is the expression of type picture?\\\hline
point of\index{point of?\texttt{point of}}& numeric& path& pair& \pageref{Dpntof}& Point on a path given a time value\\\hline
-postcontrol of\index{postcontrol?\texttt{postcontrol}}& numeric& path& pair& --& First B\'ezier control point on path segment starting at the given time\\\hline
-precontrol of\index{precontrol?\texttt{precontrol}}& numeric& path& pair& --& Last B\'ezier control point on path segment ending at the given time\\\hline
+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 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
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-refman.tex b/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-refman.tex
index aefa619a46b..614b6f3be7f 100644
--- a/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-refman.tex
+++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpman-app-refman.tex
@@ -1,4 +1,4 @@
-\svnInfo $Id: mpman-app-refman.tex 1128 2009-12-22 08:52:28Z taco $
+\svnInfo $Id: mpman-app-refman.tex 1381 2010-10-08 16:13:03Z stephanhennig $
\section{Reference Manual}
\label{refman}
@@ -8,7 +8,7 @@
\setcounter{topnumber}{10}
\setcounter{totalnumber}{10}
-\subsection{The MetaPost language}
+\subsection{The MetaPost Language}
\label{refman:lang}
Tables \ref{ivartab}--\ref{pseudotab} summarize the built-in features of
@@ -77,48 +77,49 @@ $$\begin{tabular}{|l|r|l|}
\hline
\hline
\pl\tt ahangle& \pageref{Dahangle}&
- angle for arrowheads in degrees (default: 45)\\\hline
+ Angle for arrowheads in degrees (default: 45)\\\hline
\pl\tt ahlength& \pageref{Dahlength}&
- size of arrowheads (default: 4{\tt bp})\\\hline
+ Size of arrowheads (default: 4{\tt bp})\\\hline
\pl\tt bboxmargin& \pageref{Dbbmargin}&
- extra space allowed by {\tt bbox} (default 2{\tt bp})\\\hline
+ Extra space allowed by {\tt bbox} (default 2{\tt bp})\\\hline
\tt charcode& \pageref{Dcharcode}&
- the number of the current figure\\\hline
-\tt day& --&
- the current day of the month\\\hline
+ 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
+ The initial color model (default: 5, rgb)\\\hline
\pl\tt defaultpen& \pageref{Ddefaultpen}&
- numeric index used by {\tt pickup} to select default pen\\\hline
+ Numeric index used by {\tt pickup} to select default pen\\\hline
\pl\tt defaultscale& \pageref{Ddfscale}&
- font scale factor for label strings (default 1)\\\hline
-\tt hour& --&
- the hour of the day this job started\\\hline
+ 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
\pl\tt labeloffset& \pageref{Dlaboff}&
- offset distance for labels (default 3{\tt bp})\\\hline
+ Offset distance for labels (default 3{\tt bp})\\\hline
\tt linecap& \pageref{Dlinecap}&
0 for butt, 1 for round, 2 for square\\\hline
\tt linejoin& \pageref{Dlinejoin}&
0 for mitered, 1 for round, 2 for beveled\\\hline
-\tt minute& --&
- the minute of the hour this job started\\\hline
+\tt 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& --&
- the current month (e.g, 3 $\equiv$ March)\\\hline
-\tt mpprocset& --&
- \vtop{\hbox{set this to~1 if you want to include a PostScript
-dictionary}\hbox{of abbreviations in the output}}\\\hline
+ 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 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
+ Restore the graphics state after clip operations (default: 1)\\\hline
\tt showstopping& --&
${}>0$ to stop after each {\tt show} command\\\hline
-\tt time& --&
- the number of minutes past midnight when this job started\\\hline
+\tt 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}&
@@ -144,13 +145,13 @@ dictionary}\hbox{of abbreviations in the output}}\\\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
+ Set to~1 if a {\tt -troff} or {\tt -T} option was given\\\hline
\tt truecorners& \pageref{Dtruecorn}&
${}>0$ to make {\tt llcorner} etc. ignore {\tt setbounds}\\\hline
\tt warningcheck& \pageref{Dwarncheck}&
- controls error message when variable value is large\\\hline
-\tt year& --&
- the current year (e.g., 1992)\\\hline
+ Controls error message when variable value is large\\\hline
+\tt year& \pageref{Dyear}&
+ The current year (e.g., 1992)\\\hline
\end{tabular}
$$
\label{ivartab}%
@@ -194,7 +195,7 @@ $$\begin{tabular}{|l|l|r|l|}
\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
+ 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}&
@@ -274,7 +275,7 @@ $$\begin{tabular}{|l|l|r|l|}
\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
+ 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& --&
@@ -347,9 +348,9 @@ $$\begin{tabular}{|l|r|l|}
\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
+ Read font map entries from file\\\hline
\tt \verb|fontmapline|& \pageref{Dfontmapline}&
- declare a font map entry\\\hline
+ Declare a font map entry\\\hline
\tt \verb|interim|& \pageref{Dinterm}&
Make a local change to an internal variable\\\hline
\tt \verb|let|& --&
@@ -369,15 +370,15 @@ $$\begin{tabular}{|l|r|l|}
\tt \verb|shipout|& \pageref{Dship}&
Low-level command to output a figure\\\hline
\tt \verb|show|& \pageref{Dshow}&
- print out expressions symbolically\\\hline
+ Print out expressions symbolically\\\hline
\tt \verb|showdependencies|& \pageref{Dshdep}&
- print out all unsolved equations\\\hline
+ Print out all unsolved equations\\\hline
\tt \verb|showtoken|& \pageref{Dshtok}&
- print an explanation of what a token is\\\hline
+ Print an explanation of what a token is\\\hline
\tt \verb|showvariable|& \pageref{Dshvar}&
- print variables symbolically\\\hline
+ Print variables symbolically\\\hline
\tt \verb|special|& \pageref{Dspecl}&
- print a string directly in the PostScript output file\\\hline
+ 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}&
@@ -799,93 +800,161 @@ $\tt \descr{suffix list} \rightarrow \descr{suffix} \;|\; \descr{suffix list}\hb
\endgroup
-\subsection{Command-line syntax}
+\subsection{Command-Line Syntax}
\label{refman:commandline}
-\index{command-line}
\begingroup
\renewcommand*{\arraystretch}{1.25}% Give command-line switch tables air.
-\newcommand*{\cmdindex}[1]{\index{command-line!\texttt{mpost}!\texttt{#1}}\texttt{#1}}
-\subsubsection*{The \texttt{mpost} program}
+\subsubsection{The MetaPost Program}
\label{refman:mpost}
-The command-line syntax of the MetaPost executable is
-$$ {\tt mpost}\ \descr{switches}\ \descr{file}
-$$\label{Dmpost}
-where $\descr{file}$ is a text file containing statements in the
-MetaPost language. Typically, MetaPost input files have file extension
-\texttt{.mp}\index{mp file?{\tt mp} file}\index{files!mp?{\tt mp}},
-e.g., \texttt{foo.mp}. This extension can then be omitted in the
-\texttt{mpost} call. There exist a number of command-line switches to
-control the run-time behavior of the MetaPost executable. Switches can
-prefixed by one or two dashes. Both forms have the same meaning. An
-exemplary call to MetaPost that compiles file \texttt{foo.mp}, but
-immediately exits after encountering the first error without
-user-interaction would look like:
-$$ \hbox{\tt mpost -halt-on-error foo} $$
-
-Here's a summary of the command-line switches understood by
-\texttt{mpost}:
-
-\begin{longtable}{>{\ttfamily}p{.3\linewidth}>{\raggedright\arraybackslash}p{.6\linewidth}}
+\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 \textit{dvitomp} executable (see below).\\
+ & Act as the \texttt{dvitomp} executable (see below).\\
\cmdindex{-file-line-error}
- & Start error messages with \texttt{filename:lineno:} instead of
- \texttt{!}.\\
+ & 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}
- & Be the INI variant of the program.\\
- \cmdindex{-interaction}=$\descr{string}$
- & Set interaction mode to one of \texttt{batchmode, nonstopmode,
- scrollmode, errorstopmode}.\\
- \cmdindex{-jobname}=$\descr{jobname}$
+ & 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}=$\descr{number}$
+ \cmdindex{-kpathsea-debug}=\tdescr{number}
& Set debugging flags for path searching.\\
- \cmdindex{-mem}=$\descr{string}$
- & Use $\descr{string}$ as memory dump name (same as
- \texttt{\&$\descr{string}$})\\
+ \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 \textit{kpathsea} to find files. All files have to be in
- the current directory or specified via a full path.\\
- \cmdindex{-progname}=$\descr{string}$
- & Pretend to be the $\descr{string}$ executable.\\
+ & 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{-progname}=\tdescr{string}
+ & Pretend to be the \tdescr{string} executable.\\
\cmdindex{-recorder}
& Write a list of all opened disk files to
- \texttt{$\descr{jobname}$.fls}\index{fls file?{\tt fls}
+ \texttt{\tdescr{jobname}.fls}\index{fls file?{\tt fls}
file}\index{files!fls?{\tt fls}}. (This functionality is provided
- by \textit{kpathsea}.)\\
- \cmdindex{-s}=$\descr{key}$=$\descr{value}$ \textrm{or}\newline
- -s $\descr{key}$=$\descr{value}$
- & Set internal variable $\descr{key}$ to $\descr{value}$. The
- assignment is applied just before the input file is read-in. This
- switch can be applied multiple times on the command-line.\newline
- $\descr{value}$ can be an integer between -16383 and 16383 or a string
- in double quotes. For strings, double quotes are stripped, but no
- other processing takes place.\newline
- Example: \verb|-s=outputformat="svg" -s=prologues=3|\newline
+ 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}=$\descr{texprogram}$
- & Load format $\descr{texprogram}$ for rendering \TeX\ material.\\
+ \cmdindex{-tex}=\tdescr{texprogram}
+ & Load format \tdescr{texprogram} for rendering \TeX\ material.\\
\cmdindex{-troff}, \cmdindex{-T}
- & Output \textit{troff} compatible PostScript files.\\
+ & Output troff compatible PostScript files.\\
\cmdindex{-version}
& Print version information and exit.\\
\end{longtable}
The following command-line switches are silently ignored in
-\textit{mplib}-based MetaPost (v1.100 or later), because they are always
+\emph{mplib}-based MetaPost (v1.100 or later), because they are always
`on':
-\begin{longtable}{>{\ttfamily}p{.3\linewidth}>{\raggedright\arraybackslash}p{.6\linewidth}}
+
+\begin{longtable}{>{\ttfamily}p{.35\linewidth}>{\raggedright\arraybackslash}p{.6\linewidth}}
\cmdindex{-8bit}
& \\
\cmdindex{-parse-first-line}
@@ -893,55 +962,87 @@ The following command-line switches are silently ignored in
\end{longtable}
The following command-line switches are ignored, but trigger a warning:
-\begin{longtable}{>{\ttfamily}p{.3\linewidth}>{\raggedright\arraybackslash}p{.6\linewidth}}
+
+\begin{longtable}{>{\ttfamily}p{.35\linewidth}>{\raggedright\arraybackslash}p{.6\linewidth}}
\cmdindex{-no-parse-first-line}
& \\
- \cmdindex{-output-directory}=$\descr{string}$
+ \cmdindex{-output-directory}=\tdescr{string}
& \\
- \cmdindex{-translate-file}=$\descr{string}$
+ \cmdindex{-translate-file}=\tdescr{string}
& \\
\end{longtable}
-\renewcommand*{\cmdindex}[1]{\index{command-line!\texttt{dvitomp}!\texttt{#1}}\texttt{#1}}
+\end{description}
-\subsubsection*{The \texttt{dvitomp} program}
+\subsubsection{The dvitomp Program}
\label{refman:dvitomp}
-The \ttindex{dvitomp}\label{Ddvitomp} program converts DVI\index{dvi
- file?{\tt dvi} file}\index{files!dvi?{\tt dvi}} files into low-level
-MetaPost code. The command-line syntax of the executable is
-$$ \hbox{\verb|dvitomp|}\ \descr{switches}\ \descr{infile}\ \descr{outfile}
+\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}}
$$
-where $\descr{infile}$ is the DVI file to convert and $\descr{outfile}$
-contains the equivalent MetaPost code. MetaPost uses the
-\texttt{dvitomp} program when typesetting \verb|btex| \verb|...|
-\verb|etex| labels by \TeX\ for the final conversion back into MetaPost
-code. Files generated that way end with \texttt{.mpx}\index{mpx
- file?{\tt mpx} file}\index{files!mpx?{\tt mpx}}. The following
-command-line switches are accepted:
-\begin{longtable}{>{\ttfamily}p{.3\linewidth}>{\raggedright\arraybackslash}p{.6\linewidth}}
+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}=$\descr{number}$
+ \cmdindex{-kpathsea-debug}=\tdescr{number}
& Set debugging flags for path searching.\\
- \cmdindex{-progname}=$\descr{string}$
- & Pretend to be the $\descr{string}$ executable.\\
+ \cmdindex{-progname}=\tdescr{string}
+ & Pretend to be the \tdescr{string} executable.\\
\cmdindex{-version}
& Print version information and exit.\\
\end{longtable}
-The \texttt{dvitomp} program used to be part of a set of external tools,
-called \emph{mpware}\index{mpware tools}\footnote{\texttt{makempx},
- \texttt{mpto}, \texttt{dvitomp}, and \texttt{dmp}.}, that were used by
-MetaPost for processing \verb|btex| \verb|...| \verb|etex| labels.
-Since MetaPost version~1.100, the label conversion is handled internally
-by the \texttt{mpost} executable. The \emph{mpware} tools are therefore
-obsolete and no longer part of the MetaPost distribution. Nowadays, the
-\texttt{dvitomp} executable is either a copy of the \texttt{mpost}
-executable with the name \texttt{dvitomp} or a wrapper, calling
-\texttt{mpost} as
-$$ \hbox{\verb|mpost -dvitomp|}\ \descr{infile}\
-\descr{outfile}\qquad\hbox{.} $$
+\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
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpman-charts.mp b/Master/texmf-dist/doc/metapost/base/source-manual/mpman-charts.mp
new file mode 100644
index 00000000000..a1ad1e47b3b
--- /dev/null
+++ b/Master/texmf-dist/doc/metapost/base/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 + wfsegangle;% 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(btex \appl{Editor} etex, degtoxy(wfstart+wfsegangle*0)) withcolor appl_col;
+ label(btex \ext{fig.mp} etex, degtoxy(wfstart+wfsegangle*1)) withcolor ext_col;
+ label(btex \appl{MetaPost} etex, degtoxy(wfstart+wfsegangle*2)) withcolor appl_col;
+ label(btex \ext{fig.1} etex, degtoxy(wfstart+wfsegangle*3+10)) withcolor ext_col;
+ label(btex {\extfontvii fig.log} etex, degtoxy(wfstart+wfsegangle*3-10)) withcolor ext_col;
+ label(btex \appl{Previewer} etex, degtoxy(wfstart+wfsegangle*4)) withcolor appl_col;
+ label(unituserLeft scaled usersize, degtoxy(wfstart+wfsegangle*5));
+endfig;
+
+end
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpman.bib b/Master/texmf-dist/doc/metapost/base/source-manual/mpman.bib
index c476a028e02..e54ed5603e4 100644
--- a/Master/texmf-dist/doc/metapost/base/source-manual/mpman.bib
+++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpman.bib
@@ -78,7 +78,7 @@
year = 2003,
note = "\url{http://www.w3.org/TR/SVG11/}"
}
-@misc{reckdahl:epslatex,
+@manual{reckdahl:epslatex,
author = "Keith Reckdahl",
title = "Using Imported Graphics in {\LaTeX} and {pdf\LaTeX}",
month = jan,
@@ -86,3 +86,20 @@
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}"
+}
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpman.mp b/Master/texmf-dist/doc/metapost/base/source-manual/mpman.mp
index d4e81d0d08c..6c97e9d6b79 100644
--- a/Master/texmf-dist/doc/metapost/base/source-manual/mpman.mp
+++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpman.mp
@@ -16,54 +16,6 @@ vardef dotlabel@#(expr s,z) text t_ =
enddef;
-%%% TeX macro \place is only used in figure 0.
-verbatimtex
-\input texnames.sty
-\def\place#1{\vphantom{FiMP}\smash{#1}}
-etex
-
-%%% The boxes package is only used in figure 0.
-input boxes
-
-beginfig(0);
-ba.dy = bb.dy = d.dy = 12bp;
-d.dx = 100bp;
-boxit.aa(btex \place{Figures in MetaPost} etex);
-boxit.ab(btex \place{\TeX\ Document} etex);
-boxit.ba(btex \hbox to 75bp {\hfil\place{MetaPost}\hfil} etex);
-boxit.bb.(btex \hbox to 75bp {\hfil\place{\TeX\ or \LaTeX}\hfil} etex);
-boxit.ca(btex \place{Figures in PostScript} etex);
-boxit.cb(btex \place{{\tt dvi} file} etex);
-boxit.d(btex \place{\tt dvips} etex);
-boxit.e(btex PostScript etex);
-boxit.f(btex \vbox{
- \hbox to 50bp {\hfil\hbox{bounding}\hfil}
- \hbox to 50bp {\hfil\hbox{box}\hfil}
- } etex scaled .8);
-ba.n - aa.s = ca.n - ba.s
-= bb.n - ab.s = cb.n - bb.s
-= e.n - d.s = down * 25bp;
-ypart cb.s - ypart d.n = 25bp;
-e.s = origin;
-ypart ca.s = ypart cb.s;
-xpart aa.n = xpart 0.1[d.nw,d.ne];
-xpart ab.n = xpart 0.9[d.nw,d.ne];
-drawunboxed(aa,ab,ca,cb,e);
-drawboxed(ba,bb,d);
-drawarrow aa.s -- top ba.n; drawarrow ab.s -- top bb.n;
-drawarrow ba.s -- top ca.n; drawarrow bb.s -- top cb.n;
-drawarrow ca.s -- top 0.1[d.nw,d.ne];
-drawarrow cb.s -- top 0.9[d.nw,d.ne];
-drawarrow d.s -- top e.n;
-path p;
-p = ca.e{right} .. {right}bb.w;
-f.c = point .5 of p;
-drawunboxed(f);
-draw p cutafter bpath f dashed evenly;
-drawarrow p cutbefore subpath (1,3) of bpath f dashed evenly;
-endfig;
-
-
beginfig(1);
draw (20,20)--(0,0)--(0,30)--(30,0)--(0,0);
endfig;
diff --git a/Master/texmf-dist/doc/metapost/base/source-manual/mpman.tex b/Master/texmf-dist/doc/metapost/base/source-manual/mpman.tex
index c4a38d43a2c..6889d586176 100644
--- a/Master/texmf-dist/doc/metapost/base/source-manual/mpman.tex
+++ b/Master/texmf-dist/doc/metapost/base/source-manual/mpman.tex
@@ -1,4 +1,4 @@
-% $Id: mpman.tex 1219 2010-04-01 09:05:51Z taco $
+% $Id: mpman.tex 1432 2010-10-22 12:02:13Z stephanhennig $
% MetaPost manual, by John Hobby. License at end.
\listfiles
\RequirePackage{ifpdf}
@@ -12,8 +12,8 @@
\fi
\documentclass{article} % article is NOT the original style
\usepackage[nofancy]{svninfo}% Access VCS information.
-\svnInfo $Id: mpman.tex 1219 2010-04-01 09:05:51Z taco $
-\newcommand*{\mpversion}{1.211}
+\svnInfo $Id: mpman.tex 1432 2010-10-22 12:02:13Z stephanhennig $
+\newcommand*{\mpversion}{1.503}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
@@ -29,6 +29,7 @@
\usepackage[textwidth=6in,textheight=8.65in]{geometry}
\usepackage{tocloft}
\setlength\cftbeforesecskip{1.3ex plus 0.3ex minus 0.3ex}
+ \setcounter{tocdepth}{2}
\usepackage{ltxtable}
@@ -39,7 +40,7 @@
\newcommand\descr[1]{{\langle\hbox{#1}\rangle}}
\newcommand\invisgap{\nobreak\hskip0pt\relax}
-\newcommand\tdescr[1]{$\langle$\invisgap#1\invisgap$\rangle$}
+\newcommand\tdescr[1]{{\normalfont$\langle$\invisgap#1\invisgap$\rangle$}}
\newcommand\pl{\dag}
@@ -178,8 +179,8 @@ written about MetaPost. For general help, try the
\url{http://tug.org/mailman/listinfo/metapost}.
The development is currently hosted at
-\url{https://foundry.supelec.fr/projects/metapost/}; visit this site
-for the current development team members, sources, and much else.
+\url{http://foundry.supelec.fr/projects/metapost/}; visit this site for
+the current development team members, sources, and much else.
Please report bugs and request enhancements either on the
\url{metapost@tug.org} list, or through the address given above.
@@ -197,8 +198,10 @@ $$ \hbox{\verb|draw (20,20)--(0,0)--(0,30)--(30,0)--(0,0)|} $$
draws a polygonal line like this:
$$ \includegraphics{mpman-1.mps} $$
-\label{Ddrawdot}MetaPost also has a \ttt{drawdot} command to print a
-single point, as in \ttt{drawdot(30,0)}.
+MetaPost also has a
+\verb|drawdot|\index{drawdot?\texttt{drawdot}}\label{Ddrawdot} command
+to draw a single point with the current pen, as in
+\verb|drawdot (30,0)|.
What is meant by coordinates like \verb|(30,0)|? MetaPost uses the same
default coordinate system that PostScript\index{PostScript!coordinate
@@ -237,20 +240,21 @@ generality that we do not need yet. This leads to the strange looking
statement\index{pickup?\texttt{pickup}}\index{pencircle?\texttt{pencircle}}%
\index{scaled?\texttt{scaled}}
$$ \hbox{\verb|pickup pencircle scaled 4pt|} $$
-for setting the line width for subsequent \verb|draw| statements to 4 points.
-(This is about eight times the default line width).
-
-With such a wide line width, even a line of zero length comes out as a big bold
-dot\index{dots}. We can use this to make a grid of bold dots by having one
-\verb|drawdot| statement
-for each grid point. Such a repetitive sequence of \verb|draw| statements is
-best written as a pair of nested loops:\index{loops}%
-\index{for?\texttt{for}}\index{endfor?\texttt{endfor}}
-$$\begin{verbatim}
+for 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}.
@@ -275,393 +279,143 @@ $$
\end{figure}
-\section{The MetaPost workflow}
+\section{The MetaPost Workflow}
\label{workflow}
Before describing the MetaPost language in detail, let's have a look at
-how the MetaPost program is used for developing graphics: creating
-MetaPost source files, compiling sources, previewing MetaPost graphics,
-and finally including MetaPost graphics into third-party applications.
-This section also contains some technical details about MetaPost that
-are useful to know. If you're not interested in these basics right now
-you can savely skip those parts and only refer to them later.
-
-\subsection{Processing source files}
-\label{processing}
-
-To create graphics with MetaPost, you prepare a text file containing
-code in the MetaPost language and then invoke the compiler, usually by
-giving a command of the form\index{mpost?\texttt{mpost}}
-$$ {\tt mpost}\, \descr{filename} $$
-on the command-line. The syntax and program name itself are
-system-dependent; sometimes it is named \texttt{mp}. MetaPost input
-files\index{files!input} normally have names ending
-\texttt{.mp}\index{mp file?{\tt mp} file}\index{files!mp?{\tt mp}} but
-this part of the name can be omitted when invoking MetaPost. The
-command-line options provided by MetaPost are summarized in
-appendix~\ref{refman:commandline}.
-
-\paragraph{Input file}
-\label{inputfile}
-
-A MetaPost input file normally contains a sequence of
-\verb|beginfig()|\index{beginfig?\texttt{beginfig}},
-\verb|endfig|\index{endfig?\texttt{endfig}} pairs with an {\tt
- end}\index{end?\texttt{end}} statement after the last one. These are
-macros that perform various administrative functions and ensure that the
-results of all drawing operations get packaged up and translated into
-PostScript. The numeric argument to the \verb|beginfig| macro
-determines the name of the corresponding output file, whose name, by
-default, is of the form $\descr{jobname}{\tt.}\descr{n}$, where
-$\descr{jobname}$ is the base name of the graphics source file and
-$\descr{n}$ is the current argument to \verb|beginfig|. As an example,
-if a file is named {\tt fig.mp}, the output from drawing statements
-between \verb|beginfig(1)| and the next \verb|endfig| is written in a
-file {\tt fig.1}\index{files!output}.
-
-Statements can also appear outside \verb|beginfig/endfig|. Such
-statements are processed, but drawing operations generate no visible
-output. Typically, global configurations are put outside
-\verb|beginfig/endfig|, e.g., assignments to internal variables, such as
-\verb|outputtemplate| or \verb|prologues|, or a \LaTeX\ preamble
-declaration for enhanced text rendering.
-
-\paragraph{Log file and version number}
-\label{logfile}
-
-Any terminal I/O is summarized in a
-transcript\index{files!transcript}\index{transcript file} file called
-$\descr{filename}{\tt.log}$\index{log file?{\tt log}
- file}\index{files!log?{\tt log}}. This includes error messages and
-any MetaPost commands entered interactively.\footnote{A {\tt
- *}\index{*?\texttt{*}} prompt is used for interactive input and a
- {\tt **}\index{**?\texttt{**}} prompt indicates that an input file
- name is expected. This can be avoided by invoking MetaPost on a file
- that ends with an {\tt end}\index{end?\texttt{end}} command.} The
-transcript file starts with a banner line that identifies the
-version\index{version number} of MetaPost you are using. The version
-number is also written to the generated PostScript or SVG file as a
-comment (for PostScript output the \texttt{Creator}\index{Creator
- comment in PostScript output} line is used). You can also determine
-the current version from within a MetaPost program via the predefined
-constant string
-\texttt{mpversion}\index{mpversion?\texttt{mpversion}}\label{Dmpversion}
-(since version~0.9). For instance the following code
+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}
-$$\begin{verbatim}
-message "mp = " & mpversion;
-\end{verbatim}
+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
$$
-writes
-$$\begin{verbatim}[commandchars=\\\{\}]
-mp = \mpversion
+\begin{verbatim}[commandchars=\\\{\}]
+mpost \tdescr{input file}
\end{verbatim}
+\index{mpost?\texttt{mpost}}
$$
-to the console and the transcript file.
-
-\paragraph{Output format}
-\label{outputformat}
-
-MetaPost can generate graphic in two output formats: Encapsulated
-PostScript\index{PostScript!structured} (EPSF\index{EPSF}), hence the
-name, and, since version~1.200, Scalable Vector Graphics
-(SVG\index{SVG}) following version~1.1 of the SVG
-specification~\cite{w3c:svg1.1}. By default, MetaPost outputs
-PostScript files. The output format can be changed to SVG by assigning
-the value \verb|"svg"| to the internal string variable\index{internal
- variables}\index{variables!internal}
-\ttindex{outputformat}\label{Doutputformat}:
+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.
+Starting with version~1.200, MetaPost is also capable of generating
+graphics in the SVG\index{SVG} format. SVG files can be previewed with
+certain web browsers, for example Firefox~3\index{Firefox} or
+Konqueror~4.2\index{Konqueror}.
-$$\begin{verbatim}
-outputformat := "svg";
-\end{verbatim}
+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 and is 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 SVG 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
$$
-
-Any other value makes MetaPost fall back to PostScript output. Variable
-\verb|outputformat| is case-sensitive, so assigning it the string
-\verb|"SVG"| enables PostScript output, too. Default value of variable
-\verb|outputformat| is \verb|"eps"|.
-
-\paragraph{Output file names}
-\label{outputfilenames}
-
-As discussed earlier, by default, every
-\verb|beginfig/endfig| group in an input file corresponds to an output
-file that follows the naming scheme $\descr{jobname}{\tt.}\descr{n}$.
-That is, all files have varying numeric file extensions. MetaPost
-provides a template mechanism that allows for more flexible output file
-names. The template mechanism uses \ttt{printf}-style escape sequences
-that are re-evaluated at ship-out time, i.e., before each figure is
-written to disk.
-
-To configure the output file naming scheme a string containing the
-corresponding escape sequences has to be assigned to the internal string
-variable\index{internal variables}\index{variables!internal}
-\ttt{outputtemplate}%
-\index{outputtemplate?\texttt{outputtemplate}}\label{Doutputtemplate}.
-The escape sequences provided are listed in table~\ref{tab:fntmpl}. If
-this code is saved in a file \ttt{fig.mp},
-
-$$\begin{verbatim}
-outputtemplate := "%j-%3c.mps";
+\begin{verbatim}[commandchars=\\\{\}]
beginfig(1);
- draw origin--(100,100);
+ \tdescr{drawing statements}
endfig;
+end
\end{verbatim}
$$
-it will create the output file \ttt{fig-001.mps} instead of \ttt{fig.1}.
-The file extension \texttt{.mps}\index{mps file?{\tt mps}
- file}\index{files!mps?{\tt mps}} is conventionally chosen for
-MetaPost's PostScript output (see section~\ref{teximport}). For SVG
-output one would want to use \texttt{.svg}\index{svg file?{\tt svg}
- file}\index{files!svg?{\tt svg}} instead.
-
-%\suppressfloats[t]
-\begin{table}
- \def\d{$\langle$0-9$\rangle$}
- \centering
- \begin{tabular}{|>{\ttfamily}l|>{\ttfamily}l|l|}
- \hline
- \multicolumn1{|c|}{Escape sequence} & \multicolumn1{c|}{Equivalent}
- & \multicolumn1{c|}{Meaning}\\\hline
- \%\%\index{\%\%?\texttt{\%\%}} & & percent sign\\
- \%\d\{$\descr{internal
- variable}$\}\index{\%\{...\}?\texttt{\%\{\ldots\}}} & & evaluate
- internal variable\\
- \%j\index{\%j?\texttt{\%j}} & \%\{jobname\} & current jobname\\
- \%\d c\index{\%c?\texttt{\%c}} & \%\d\{charcode\} & charcode value (\verb|beginfig|
- argument)\\
- \%\d y\index{\%y?\texttt{\%y}} & \%\d\{year\} & current year\\
- \%\d m\index{\%m?\texttt{\%m}} & \%\d\{month\} & month (numeric)\\
- \%\d d\index{\%d?\texttt{\%d}} & \%\d\{day\} & day of the month\\
- \%\d H\index{\%H?\texttt{\%H}} & \%\d\{hour\} & hour\\
- \%\d M\index{\%M?\texttt{\%M}} & \%\d\{minute\} & minute\\
- \hline
- \end{tabular}
- \caption{Allowed escape sequences for \ttt{outputtemplate}}
- \label{tab:fntmpl}
-\end{table}
-
-The template mechanism can also be used for naming graphic files
-individually, yet keeping all sources in one file. E.\,g., collecting
-different diagram sources in a file \ttt{fig.mp}
-
-$$\begin{verbatim}
-outputtemplate := "fig-quality.mps";
-beginfig(1);
- ...
-endfig;
-
-outputtemplate := "fig-cost-vs-productivity.mps";
-beginfig(2);
- ...
-endfig;
-\end{verbatim}
+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{\%}}, 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:
$$
-it might be easier to recall the correct diagram names in a \TeX\
-document than with numbered file names. Note, the argument to
-\verb|beginfig| is not relevant as long as there's no \ttt{\%c} pattern
-in the file name template string.
-
-To ensure compatibility with older files, the default value of
-\ttt{outputtemplate} is \verb|%j.%c|.
-If you assign an empty string, it will revert to that default. MetaPost
-versions~1.000 to~1.102 used a different template mechanism, see
-section~\ref{Dfilenametemplate} for more information.
-
-What does one do with all the graphic files? PostScript files are
-perfectly suitable for inclusion into documents created by
-\TeX\index{TeX?\TeX} or \emph{troff}\index{troff}. The SVG format, as
-an XML descendant (Extensible Meta Language), is more aiming at
-automated data processing/interchanging and is widely used for web
-applications. The next sections deal with the import of MetaPost
-graphics into third-party applications.
-
-At this point, it seems advisable to point out, that it is good style to
-create MetaPost graphics at nearly target size. While vector graphics
-\emph{can} be scaled without quality degradation, the visual character
-of a drawing might change unintentionally at large post-processing scale
-factors, because certain properties of a drawing do not scale
-proportionally, e.g., line width or arrow size. Additionally, while
-outline fonts do scale proportionally, this is not always desired, e.g.,
-when a font is available in optical sizes, like the Computer Modern font
-family.
-
-\subsection{Previewing MetaPost graphics}
-\label{previewing}
-\index{previewing}
-\index{PostScript!previewing}
-\index{SVG!previewing}
-
-The PostScript output of MetaPost can be previewed with any decent
-PostScript viewer, e.\,g., GSview\index{GSview}.
-The situation becomes only a little bit fussy when PostScript graphics
-contain text. By default, MetaPost doesn't produce self-contained EPS
-files, e.\,g., font resources and encoding vectors are not stored in
-the output. For that reason MetaPost output containing text may be
-rendered with wrong fonts, wrong glyphs or with no text at all in a
-PostScript viewer. For a long time, the most reliable way for
-previewing was to prepare a test document that includes all MetaPost
-figures, process that with \TeX\ or \LaTeX\ and \ttindex{dvips} and
-display the resulting \ttt{ps} file in a PostScript
-viewer.\footnote{There are alternatives, though. \ttindex{mpstoeps} is
-a Perl script that automates the process outlined above.
-\ttindex{mptopdf} is another tools that converts MetaPost files to
-PDF.}
-
-However, with MetaPost version~1.000 the situation changed. Since that
-version MetaPost is able to produce self-contained EPS files, that can
-reliably be previewed, may they contain text or not. The
-new behaviour can be triggered by setting MetaPost's internal variable
-\ttt{prologues}\index{prologues?\texttt{prologues}} to~3. See
-section~\ref{Dbtex} for more information on \ttt{prologues}.
-
-Starting with version~1.200, MetaPost is also capable of producing
-SVG output. SVG files can be previewed with certain web browsers,
-for example Firefox~3\index{Firefox} or Konqueror~4.2\index{Konqueror}.
-
-\subsection{Importing MetaPost graphics in \TeX\ documents}
-\label{teximport}
-\index{TeX?\TeX!importing MetaPost files}
-\index{LaTeX?\LaTeX!importing MetaPost files}
-\index{pdfLaTeX?pdf\LaTeX!importing MetaPost files}
-\index{pdfTeX?pdf\TeX!importing MetaPost files}
-\index{ConTeXt?Con\TeX t!importing MetaPost files}
-
-MetaPost graphics in the PostScript format can be easily integreated
-into documents prepared with \TeX\ and friends. MetaPost's PostScript
-output is a low-featured dialect of the Postscript language, called
-\emph{purified EPS}, that can be converted into the Portable Document
-Format (PDF\index{PDF}) language on-the-fly. For that reason, MetaPost
-graphics can be handled by both engines, the traditional \TeX\ with an
-external output driver and the newer pdf\TeX, that contains a built-in
-PDF output driver.
-
-Figure~\ref{fig0} shows the process of including a MetaPost graphic into
-a plain \TeX\ or \LaTeX\ document. In the \TeX\ document a ``magic
-macro'' provided by the format or an external package is used for
-including a graphic file. During the typesetting stage, the macro only
-reads bounding box information off the PostScript file and reserves the
-required space on the page via an empty box. The file reference is
-passed-on to the output driver and only then, finally, the file is
-embedded into the document. The freely available program
-\ttindex{dvips} is used as an output driver in this
-example.\footnote{The C source for \ttt{dvips} comes with the web2c
- \TeX\ distribution. Similar programs are available from other
- sources.} The next paragraphs give brief information on some popular
-combinations of formats and engines.
-
-\begin{figure}[htp]
-$$ \includegraphics{mpman-0.mps} $$
-\caption[A diagram of the processing for a document with MetaPost figures]
- {A diagram of the processing for a \TeX\ document with figures
- in MetaPost}
-\label{fig0}
-\end{figure}
-
-\paragraph{Plain \TeX\ with \TeX}
-For users of \TeX\ with traditional DVI output the
-\ttt{epsf}\index{epsf.tex?\texttt{epsf.tex}} package provides the
-``magic macro''
-$$ \verb|\epsfbox{|\descr{filename}\verb|}|%
-\index{epsfbox?\texttt{\string\epsfbox}} $$
-for embedding graphics, e.g., \verb|\epsfbox{fig.1}|.
-
-\paragraph{Plain \TeX\ with pdf\TeX}
-Users of Plain \TeX\ and pdf\TeX\ should refer to the standalone macros
-of the \ttindex{mptopdf} bundle, that can be found at
-\url{http://context.aanhet.net/mptopdf.htm}.
-
-\paragraph{\LaTeX\ format}
-For \LaTeX\ documents the well-known \ttindex{graphics} (or
-\ttindex{graphicx}) package aids in external graphics inclusion. The
-package supports different engines and can handle several graphic
-formats. The ``magic macro'' is
-$$ \verb|\includegraphics{|\descr{filename}\verb|}|%
-\index{includegraphics?\texttt{\string\includegraphics}} $$
-
-When the \ttt{dvips} driver is chosen, the \ttt{graphics} package
-assumes all files with an unknown file extension to be in the EPS
-format. MetaPost files with a numeric default file extension are
-therefore handled correctly -- even if only in a fall-back procedure
-(see~\cite{reckdahl:epslatex} for more information).
-
-For the pdf\TeX\ driver, the situation is a bit different. Only files
-with file extension \texttt{.mps}\index{mps file?{\tt mps}
- file}\index{files!mps?{\tt mps}} are recognized as purified EPS and
-can be converted to PDF\index{PDF} on-the-fly. The recommended
-procedure for including MetaPost graphics into \LaTeX\ documents
-compiled with the pdf\TeX\ engine should be obvious: change MetaPost's
-output file naming scheme to write files ending \texttt{.mps} via
-\verb|outputtemplate|\index{outputtemplate?\texttt{outputtemplate}} (see
-p.~\pageref{Doutputtemplate}). In the \LaTeX\ document include the
-graphic files with full name, e.g.,
-$$\begin{verbatim}
-\includegraphics{fig-1.mps}
-\end{verbatim}
-$$
-
-Note, the latter approach works with the \ttt{dvips} driver, too. Even
-though, again, this time \ttt{.mps} is an unknown file extension and
-triggers EPS file handling in the fall-back procedure. This property of
-the \ttt{graphics} package, that comes in handy for MetaPost files, is
-the reason many MetaPost source files start with the line
-$$\begin{verbatim}
-outputtemplate := "%j-%c.mps";
-\end{verbatim}
-$$
-
-\paragraph{Con\TeX t}
-In Con\TeX t\index{ConTeXt?Con\TeX t} support of MetaPost is integrated
-in the kernel. Apart from inline graphics (see MetaFun\index{MetaFun}
-manual), one can embed graphics explictely with the
-\verb+\externalfigure+%
-\index{externalfigure?\texttt{\string\externalfigure}} command.
-Numbered graphics are recognized automatically, as are graphics with the
-\ttt{mps} suffix. Special features like shading, transparency, image
-inclusion, color spaces and such are handled automatically. In practice
-Con\TeX t users will probably define MetaPost graphics in the document
-source which has some advantages, like a more natural interfacing with
-document properties, font support, and automatic processing. Support
-for MetaPost inclusion is present in the versions MkII as well as MkIV,
-but the used methods are slightly different. Future versions of MkIV
-will support an even more tight integration.
-
-\subsection{Importing MetaPost graphics in \emph{troff} documents}
-\label{troffimport}
-\index{troff!importing MetaPost files}
-
-It is also possible to include MetaPost output in a GNU \emph{troff}
-document. The procedure is similar to Figure~\ref{fig0}: the
-\ttt{grops} output processor includes PostScript files when they are
-requested via \emph{troff}'s \ttt{\string\X} command. The
-\ttt{-mpspic}\index{mpspic?\texttt{-mpspic}} macro package provides a
-command \verb|.PSPIC|\index{PSPIC?\texttt{.PSPIC}}, that does just that
-when including an encapsulated PostScript file in the source code. For
-instance, the \emph{troff} command
-$$ \hbox{\verb|.PSPIC fig.1|} $$
-includes \ttt{fig.1}, using the natural height and width of the
-image as given in the file's bounding box.
-
-\subsection{Handling SVG files}
-\label{svgimport}
-\index{SVG!third-party applications}
-
-SVG graphics can be easily embedded into HTML\index{HTML} documents with
-the following code snippet:
-
-$$\begin{verbatim}
-<p>
- <object data="foo.svg" type="image/svg+xml" width="300" height="200">
- </object>
-</p>
+\begin{verbatim}[commandchars=\\\{\}]
+prologues := 3; \smallskip
+outputtemplate := "%j-%c.mps"; \smallskip
+outputformat := "svg";
\end{verbatim}
$$
-SVG files can also be imported by various interactive graphics editing
-programs, for example GIMP\index{GIMP} or Inkscape\index{Inkscape}. See
-section~\ref{Dprologues} for information on font handling in SVG
-graphics.
+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}
@@ -761,6 +515,9 @@ draw (0,0)..controls (26.8,-1.8) and (51.4,14.6)
\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}
$$
@@ -1317,8 +1074,10 @@ function of pens in MetaPost is to determine line thickness, but they
can also be used to achieve calligraphic effects. The
statement\index{pickup?\texttt{pickup}}\label{Dpickup}
$$ {\tt pickup\ }\descr{pen expression} $$
-causes the given pen to be used in subsequent {\tt draw} statements.
-Normally, the pen expression is of the form
+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
@@ -1829,7 +1588,11 @@ 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.
+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
@@ -2024,7 +1787,7 @@ In MetaPost versions before 1.100, the \TeX\ label preprocessing was
handled by an external program that was called upon automatically by
MetaPost. On Web2C-based systems, the preprocessor was normally named
\ttindex{makempx}, which called the utility \ttindex{mpto} for the
-creation of the \TeX\ input file and the utility \ttindex{dvitomp} for
+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
@@ -2102,17 +1865,50 @@ will contain the PostScript font(s) (or a subset) used based on the
for generating stand-alone PostScript graphics.
In SVG mode, the font glyphs are converted to path definitions that
-are included at the top of the output file. This method is currently
-the only reliable way to export text objects to SVG.
+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.
+
+\end{description}
-It is worth noting that the default value \ttt{prologues:=0} is sufficient
-for graphics included in \TeX-based documents. Also, the \ttt{prologues} variable is irrelevant
-when processing MetaPost files through the \ttindex{mptopdf} utility
-(part of the \ConTeXt\ distribution), because PDF files are, by nature,
-stand-alone. Moreover, the value of \ttt{prologues} has no effect on
+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.
@@ -2120,14 +1916,14 @@ handle those.
The details on how to include PostScript figures in a paper
done in \TeX\ or troff are system-dependent. They can generally be found
in manual pages and other on-line documentation, but have a look at
-section~\ref{teximport} of this manual for some brief instructions that
+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}
+\subsection{Font Map Files}
\label{fontmap}
If \ttt{prologues} is set to~2, any used fonts in the output file are
@@ -2193,18 +1989,18 @@ pdftex.map}, depending on whether or not troff mode is enabled. If
statement. Again, this is for backward compatibility only.
-\subsection{The \texttt{infont} operator}
+\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
+ 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
+ primary} as its right argument. The left argument is text, and the
right argument is a font name. The result of the operation is a
-\tdescr{picture secondary} that can then be transformed in various ways.
-One possibility is enlargement by a given factor via the
+\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
@@ -2674,6 +2470,31 @@ 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}
$$
@@ -3544,7 +3365,7 @@ $$ {\tt shipout}\, \descr{picture expression} $$
writes out a picture as a PostScript\index{PostScript} file whose
file name is determined by
{\tt outputtemplate}\index{outputtemplate?\texttt{outputtemplate}}
-(see section~\ref{outputfilenames}). By default, the file name ends
+(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
@@ -3781,23 +3602,25 @@ To summarize the discussion of mismatching part operators:
\index{greypart?\texttt{greypart}|)}
-\subsection{Decomposing the glyphs of a font}
+\subsection{Decomposing the Glyphs of a Font}
\label{glyphs}
-MetaPost provides a primitive to convert a glyph of a font in the Adobe
-Type~1 Font\index{PostScript!fonts}\index{font!PostScript}\index{Adobe
- Type~1 Font}\index{font!Adobe Type~1} format into its constituent
-filled paths---the strokes---and store them in a picture variable. A
-glyph\index{font!glyph} is the visual representation of a character in a
-font. A character\index{character}\index{font!character} is a certain
-slot\index{slot} (index) in a font with an associated meaning, e.g., the
-capital letter~``M'' or the exclamation mark. The meaning of a slot is
-defined by the font encoding\index{encoding}\index{font!encoding}. In
-general, the same character is represented by different glyphs in
-different fonts. Figure~\ref{glyphsample} shows some glyphs for the
-character at slot~103 in the T1 encoding, i.e., the lower-case
-letter~``g''. All glyphs are at the same nominal size. Note, how
-glyphs may extend beyond their bounding box.
+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}
@@ -3819,8 +3642,8 @@ glyphs may extend beyond their bounding box.
\label{glyphsample}
\end{figure}
-The glyphs of an Adobe Type~1 font
-\index{PostScript!fonts}\index{font!PostScript}\index{Adobe Type~1
+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
@@ -3862,17 +3685,19 @@ glyph visually\footnote{Plain contours already carry enough information
fonts\index{PostScript!fonts}\index{font!PostScript}\index{Adobe Type~1
Font}\index{font!Adobe Type~1} use a generalized variant of the
non-zero winding number fill rule\index{non-zero fill rule}\index{fill
- rule!non-zero}\index{PostScript!fill rule}, that MetaPost doesn't
+ 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 Modern
-Roman\index{Computer Modern Roman} font in a picture variable:
+encoding\index{OT1 encoding}\index{encoding!OT1}, in the
+Computer\index{Computer Modern Roman} Modern Roman font in a picture
+variable:
-$$\begin{verbatim}
+$$
+\begin{verbatim}
fontmapline "cmr10 CMR10 <cmr10.pfb";
picture g;
g := glyph 103 of "cmr10";
@@ -3893,7 +3718,7 @@ is mandatory for the font in question, given either by
section~\ref{Dfontmapline}).
In Figure~\ref{fig56}, the contours of the upper case letter~``\v{D}''
-in the Latin Modern Roman\index{Latin Modern Roman} font are saved in a
+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
@@ -3901,7 +3726,8 @@ draws them together with their cardinal (black) and control points
cardinal points in this glyph.
\begin{figure}[htb]
-$$\begin{verbatim}
+$$
+\begin{verbatim}
fontmapfile "=lm-ec.map";
beginfig(56);
picture q;
@@ -3945,13 +3771,13 @@ negative). Second, in an Adobe Type~1
font\index{PostScript!fonts}\index{font!PostScript}\index{Adobe Type~1
Font}\index{font!Adobe Type~1}, contours are in general closed by
repeating the starting point before applying the \verb|closepath|
-operator\index{PostScript!\texttt{closepath} operator}. The MetaPost
-representation of such a path would be:
+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|
$$
-A more natural MetaPost representation of this path would be:
+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|
@@ -3959,20 +3785,20 @@ $$
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
+operator is scaled, such that one font design unit\index{font!design
unit} equals one PostScript
point\index{point!PostScript}\index{PostScript!point} (bp). A usual
font design unit is a thousandth part of the font design
-size\index{font!design size}. The returned picture will therefore
-typically have a height of around 1000\,bp.
+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.'' When flattening
-text, all hinting information in fonts are lost. Hinting information
-aid a rendering application in aligning certain parts of a glyph on a
+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, when the internal variable
+flattened, if the internal variable
\verb|prologues|\index{prologues?\texttt{prologues}} is set to~3 (see
section~\ref{Dprologues}).
@@ -4981,7 +4807,7 @@ Explanation:
\begin{itemize}
\item
-The \texttt{\%\&latex} causes \LaTeX\ to be invoked instead of \TeX.
+The \texttt{\%\&latex}\index{\%\&?\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
@@ -5027,18 +4853,424 @@ whatever processor, of course). This might be useful from a Makefile,
or just a one-off run.
\end{itemize}
-\subsection{\texttt{mproof.tex}}
-\index{mproof.tex?\texttt{mproof.tex}}
+\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
+output one would want to use \texttt{svg}\index{svg file?{\tt svg}
+ file}\index{files!svg?{\tt svg}} instead.
+
+\begin{table}
+ \newcommand*{\otesc}[3]{\%#1\index{\%#1?\texttt{\%#1}} & #2 & \%\{#3\}}
+ \centering
+ \begin{tabular}{|>{\ttfamily}l|l|>{\ttfamily}l|}
+ \hline
+ \multicolumn1{|c|}{Escape sequence} & \multicolumn1{c|}{Meaning} & \multicolumn1{c|}{Alternative}\\\hline
+ \%\%\index{\%\%?\texttt{\%\%}} & percent sign &\\
+ \%\{\tdescr{internal variable}\}\index{\%\{...\}?\texttt{\%\{\tdescr{internal variable}\}}} & evaluate internal variable &\\
+ \%j\index{\%j?\texttt{\%j}} & current jobname & \%\{jobname\} \\
+ \otesc{c}{charcode value (\texttt{beginfig} argument)}{charcode}\\
+ \otesc{y}{current year}{year}\\
+ \otesc{m}{month (numeric)}{month}\\
+ \otesc{d}{day of the month}{day}\\
+ \otesc{H}{hour}{hour}\\
+ \otesc{M}{minute}{minute}\\
+ \hline
+ \end{tabular}
+ \caption{Allowed escape sequences for \ttt{outputtemplate}}
+ \label{tab:outputtemplate}
+\end{table}
-\texttt{mproof.tex} is a (plain) \TeX\ routine, not MetaPost at all. It
-writes a proof sheet for MetaPost output. Call it like this:
+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, there can
+be an optional number (0--99) following \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 exceeds the requested length.
+If less digits are required, the string is padded to the requested
+length with zeros from left.
+
+In the \verb|%{...}| escape sequence no rounding takes place.
+Additionally, neither this nor single-letter escape sequences referring
+to internal string variables can be zero-padded.
+
+For backwards compatibility, the \verb|%c|\index{\%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| (bypassing the rounding, too).
-$$\hbox{\tt tex mproof {\sl MetaPost-output-filename}}$$
+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.
+
+\paragraph{Output Format}
+
+MetaPost can generate graphics in two output formats: Encapsulated
+PostScript\index{PostScript!structured} (EPSF\index{EPSF}) and, since
+version~1.200, Scalable Vector Graphics (SVG\index{SVG}) following
+version~1.1 of the SVG specification~\cite{w3c:svg1.1}. By default,
+MetaPost outputs PostScript files---hence the name MetaPost. The output
+format can be changed to SVG by assigning the value \verb|"svg"| to the
+internal string variable\index{internal
+ variables}\index{variables!internal}
+\verb|outputformat|\index{outputformat?\texttt{outputformat}}\label{Doutputformat}:
+$$
+\begin{verbatim}
+outputformat := "svg";
+\end{verbatim}
+$$
+
+Any other value makes MetaPost fall back to PostScript output. Variable
+\verb|outputformat| is case-sensitive, so assigning it the string
+\verb|"SVG"| enables PostScript output, too. Default value of variable
+\verb|outputformat| is \verb|"eps"|.
+
+\paragraph{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 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. 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.
+ 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}
+$$
-\section{Debugging}
+\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.
@@ -5232,6 +5464,241 @@ 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}
+\index{SVG!files}
+
+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} 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}
+$$
+
+SVG files can also be imported by various interactive graphics editing
+programs, for example GIMP\index{GIMP} or Inkscape\index{Inkscape}. See
+Section~\ref{Dprologues} for information on font handling in SVG
+graphics.
+
\section*{Acknowledgement}