From 3bd11c5b320d265b89c965f63f57018ef818b876 Mon Sep 17 00:00:00 2001 From: Taco Hoekwater Date: Tue, 5 Apr 2011 14:13:11 +0000 Subject: Update to metapost 1.503 git-svn-id: svn://tug.org/texlive/trunk@21975 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/metapost/base/mpboxes.pdf | Bin 371620 -> 371601 bytes Master/texmf-dist/doc/metapost/base/mpgraph.pdf | Bin 467533 -> 467471 bytes Master/texmf-dist/doc/metapost/base/mpintro.pdf | Bin 234860 -> 234688 bytes Master/texmf-dist/doc/metapost/base/mplibapi.pdf | Bin 0 -> 243123 bytes Master/texmf-dist/doc/metapost/base/mpman.pdf | Bin 858284 -> 895061 bytes .../doc/metapost/base/source-manual/Makefile | 30 +- .../doc/metapost/base/source-manual/README | 6 +- .../doc/metapost/base/source-manual/TODO | 41 +- .../doc/metapost/base/source-manual/charts.mp | 120 ++ .../doc/metapost/base/source-manual/mp.1 | 289 ----- .../doc/metapost/base/source-manual/mpboxes.bib | 1 - .../base/source-manual/mpman-app-legacy.tex | 686 +++++----- .../base/source-manual/mpman-app-optab.tex | 10 +- .../base/source-manual/mpman-app-refman.tex | 351 +++-- .../metapost/base/source-manual/mpman-charts.mp | 210 +++ .../doc/metapost/base/source-manual/mpman.bib | 19 +- .../doc/metapost/base/source-manual/mpman.mp | 48 - .../doc/metapost/base/source-manual/mpman.tex | 1363 +++++++++++++------- 18 files changed, 1894 insertions(+), 1280 deletions(-) create mode 100644 Master/texmf-dist/doc/metapost/base/mplibapi.pdf create mode 100644 Master/texmf-dist/doc/metapost/base/source-manual/charts.mp delete mode 100644 Master/texmf-dist/doc/metapost/base/source-manual/mp.1 create mode 100644 Master/texmf-dist/doc/metapost/base/source-manual/mpman-charts.mp (limited to 'Master/texmf-dist/doc/metapost/base') diff --git a/Master/texmf-dist/doc/metapost/base/mpboxes.pdf b/Master/texmf-dist/doc/metapost/base/mpboxes.pdf index 3a0182c4e20..f06e8847a64 100644 Binary files a/Master/texmf-dist/doc/metapost/base/mpboxes.pdf and b/Master/texmf-dist/doc/metapost/base/mpboxes.pdf 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 Binary files a/Master/texmf-dist/doc/metapost/base/mpgraph.pdf and b/Master/texmf-dist/doc/metapost/base/mpgraph.pdf 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 Binary files a/Master/texmf-dist/doc/metapost/base/mpintro.pdf and b/Master/texmf-dist/doc/metapost/base/mpintro.pdf 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 Binary files /dev/null and b/Master/texmf-dist/doc/metapost/base/mplibapi.pdf 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 Binary files a/Master/texmf-dist/doc/metapost/base/mpman.pdf and b/Master/texmf-dist/doc/metapost/base/mpman.pdf 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 withpen" and "label(, ...) 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 +% . The original SVG file by +% 'yyycatch' is licensed as Public Domain and can be found at +% . It has been +% converted to MetaPost by exporting the SVG file to EPS in Inkscape +% and then coordinates, colours and pens have been manually translated +% to the corresponding MetaPost commands. + path p[]; + p1 = + (39.387, 60.034) .. controls (17.117, 59.401) and (-0.352, 22.932) + .. (7.887, 10.565) .. controls (16.125, -1.802) and (64.465, -1.802) + .. (72.34, 10.565) .. controls (80.215, 22.932) and (62.383, 60.686) + .. cycle; + p2 = + (22.809, 52.588) + -- (59.93, 52.588) .. controls (59.93, 52.588) and (60.523, 15.705) + .. (47.293, 15.705) .. controls (34.852, 15.705) and (22.809, 52.588) + .. cycle; + p3 = + (69.125, 67.963) .. controls (69.125, 50.881) and (56.723, 37.037) + .. (41.422, 37.037) .. controls (26.125, 37.037) and (13.723, 50.881) + .. (13.723, 67.963) .. controls (13.723, 85.045) and (26.125, 98.893) + .. (41.422, 98.893) .. controls (56.633, 98.893) and (69, 85.198) + .. cycle; + p4 = + (31.047, 76.764) .. controls (31.047, 76.764) and (43.93, 63.147) + .. (57.152, 64.209) .. controls (70.398, 65.276) and (79.316, 71.444) + .. (79.316, 71.444) .. controls (79.316, 71.444) and (72.488, 108.674) + .. (41.977, 109.291) .. controls (18.086, 109.791) and (6.324, 86.862) + .. (2.84, 71.444) .. controls (-0.691, 55.83) and (4.152, 55.889) + .. (9.313, 57.221) .. controls (14.477, 58.549) and (31.047, 76.764) + .. cycle; + p5 = + (84.211, 30.416) .. controls (87.586, 25.877) and (85.977, 18.955) + .. (80.617, 14.967) .. controls (75.258, 10.979) and (68.164, 11.428) + .. (64.785, 15.971) + -- (64.734, 16.037) .. controls (62.766, 18.741) and (62.41, 30.342) + .. (65.918, 32.764) .. controls (69.781, 35.428) and (80.832, 34.955) + .. cycle; + interim linecap := butt; + interim linejoin := mitered; + fill p1 withcolor (1, 0.501961, 0.501961); + draw p1 withcolor 0.219608 withpen pencircle scaled 2.577288; + fill p2 withcolor 1; + draw p2 withcolor 0.219608 withpen pencircle scaled 2.782928; + fill p3 withcolor (1, 0.8, 0.666667); + draw p3 withcolor 0.219608 withpen pencircle scaled 3.31912; + fill p4 withcolor (0.827451, 0.552941, 0.372549); + draw p4 withcolor 0.219608 withpen pencircle scaled 3.262816; + fill p5 withcolor (1, 0.8, 0.666667); + draw p5 withcolor 0.219608 withpen pencircle scaled 2.4; + ); +% Normalize user icon. + unituserRight := unituserRight shifted (-llcorner unituserRight -.5urcorner unituserRight); + unituserRight := unituserRight scaled (.5/ypart urcorner unituserRight); + unituserLeft := unituserRight reflectedabout ((0,0), (0,1)); + +% Helper function: transform location on workflow circle in +% degrees into cartesian coordinates. + def degtoxy(expr deg) = + (point deg/45 of fullcircle scaled wfdiam) + enddef; + +% Draw workflow segments. + for i=0 upto wfsegments-1: + fill wfseg scaled wfdiam rotated (wfstart+i*wfsegangle) withcolor wf_col; + endfor + +% Fill-in workflow segment descriptions. + label(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} -

- - -

+\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 {\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} +

+ + +

+\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} -- cgit v1.2.3