MetaPost is a picture-drawing language similar to Metafont (see section 5. Metafont: Creating typeface families), but instead of outputting bitmaps in a "font", it outputs PostScript commands. It's primarily intended for creating technical illustrations.
MetaPost also provides for arbitrary integration of text and graphics in a natural way, using any typesetter (TeX and Troff are both supported) and a number of other subsidiary programs, described below.
mpost invocation
MetaPost (installed as mpost) reads a series of pictures
specified in the MetaPost programming language, and outputs
corresponding PostScript code. This section merely describes the
options available in the Web2c implementation. For a complete
description of the MetaPost language, see AT&T technical report
CSTR-162, generally available as the file
`texmf/doc/metapost/mpman.ps', where texmf is the root of
TeX directory structure. See also
http://cm.bell-labs.com/who/hobby/MetaPost.html.
Also, a standard MetaPost package for drawing graphs is documented in AT&T technical report CSTR-164, available as the file `mpgraph.ps', generally stored alongside `mpman.ps'.
MetaPost processes its command line and determines its memory dump (mem)
file in a way exactly analogous to Metafont and TeX (see section 4.1 tex invocation, and see section 3.5.2 Memory dumps).
Synopses:
mpost [option]... [mpname[.mp]] [mp-commands] mpost [option]... \first-line mpost [option]... &mem args
MetaPost searches the usual places for the main input file mpname
(see section `Supported file formats' in Kpathsea), extending
mpname with `.mp' if necessary. To see all the relevant
paths, set the environment variable KPATHSEA_DEBUG to `-1'
before running the program.
MetaPost writes its PostScript output to a series of files
`basempname.nnn' (or perhaps
`basempname.ps', very occasionally
`basempname.tfm'), where nnn are the figure numbers
specified in the input, typically to the beginfig macro, and
basempname is the basename of mpname, or `mpout' if no
input file was specified. MetaPost uses the `.ps' extension when
the figure number is out of range, e.g., if you say beginfig(-1).
You can use the output files as figures in a TeX document just as with any other PostScript figures. For example, with this TeX command:
\special{psfile="filename"}
or by using `epsf.tex' (see section `EPSF macros' in Dvips).
btex ... tex-input ... etex
calls MakeMPX to generate a MPX file containing a MetaPost picture expression corresponding to tex-input (see section 6.4 MakeMPX: Support MetaPost labels).
The construct
verbatimtex ... tex-input ... etex
simply passes the tex-input through to MakeMPX and thus to
TeX. For example, if you are using LaTeX, your MetaPost input file
must start with a verbatimtex block that gives the necessary
\documentclass (or \documentstyle)
\begin{document} command. You will also need to set the
enviroment variable TEX to `latex' (see section 6.4 MakeMPX: Support MetaPost labels).
tex-input need not be specifically TeX input; it could also be Troff. In that case, you will need the `-m pictures' Troff macro package (unfortunately absent from many Troff implementations), or an equivalent such as the `-m pspic' macros from GNU groff described in grops(1).
Other typesetters can be supported with no change to MetaPost itself; only MakeMPX needs to be updated.
Naturally, you must use fonts that are supported by the typesetter; specifically, you'll probably want to use standard PostScript fonts with Troff. And only the TeX system understands Computer Modern or other Metafont fonts; you can also use PostScript fonts with TeX, of course.
MetaPost-generated PostScript figures which do use Computer Modern fonts for labels cannot be directly previewed or printed. Instead, you must include them in a TeX document and run the resulting DVI file through Dvips to arrange for the downloading of the required fonts (see section `Fonts in figures' in Dvips). To help with this, the MetaPost distribution provides a small TeX file `mproof.tex' which is typically called as:
tex mproof mp-output-files... ; dvips mproof -o
The resulting file `mproof.ps' can then be printed or previewed.
To generate EPSF files, set the internal MetaPost variable
prologues positive. To make the output files self-contained, use
only standard PostScript fonts. MetaPost reads the same
`psfonts.map' file as Dvips, to determine PostScript fonts that
need to be downloaded (see section `psfonts.map' in Dvips).
MetaPost can write output files, via the write primitive; this
opens a security hole. See section 4.1 tex invocation.
The program accepts the following options, as well as the standard `-help' and `-version' (see section 3.2 Common options):
prologues internal variable to 1, and use
makempx -troff to generate MPX files.
inimpost invocation
inimpost is the "initial" form of MetaPost, which does lengthy
initializations avoided by the "virgin" (vir) form, so as to be
capable of dumping `.mem' files (see section 3.5.2 Memory dumps). For a
detailed comparison of virgin and initial forms, see section 3.5.1 Initial and virgin.
For a list of options and other information, see section 6.1 mpost invocation.
The only memory dump file commonly used with MetaPost is the default, `plain.mem', also known as `mpost.mem' (again, see section 3.5.2 Memory dumps). It is created by default during installation, but you can also do so by hand if necessary (e.g., if a MetaPost update is issued):
inimpost '\input plain dump'
(The quotes prevent interpretation of the backslashes from the shell.) Then install the resulting `plain.mem' in `$(memdir)' (`/usr/local/share/texmf/web2c' by default), and link `mpost.mem' to it.
MetaPost also provides a mem file with all the features of plain Metafont, called `mfplain.mem'. You can create that in the same way; just replace `plain' in the above command with `mfplain'. `mfplain.mem' file lets you directly process Metafont source files with MetaPost, producing character proofs (one file for each character) similar to those produced with Metafont in proof mode and GFtoDVI (see section 5.6 GFtoDVI: Character proofs of fonts).
virmpost invocation
virmpost is the "virgin" form of MetaPost, which avoids the
lengthy initializations done by the "initial" (ini) form, and
is thus what is generally used for production work. For a detailed
comparison of virgin and initial forms, see section 3.5.1 Initial and virgin.
For a list of options and other information, see section 6.1 mpost invocation.
In MetaPost, labels can be typeset using any document processor; the Web2c implementation supports TeX and Troff. MakeMPX translates the labels from the typesetting language back into low-level MetaPost commands in a so-called mpx file, so text can be manipulated like other graphic objects. It is invoked automatically by MetaPost. Synopsis:
makempx [-troff] mpfile mpxfile
The input comes from mpfile (no path searching is done), and the output goes to mpxfile. However, if the file mpxfile already exists, and is newer than mpfile, then nothing is done (presumably the file is up-to-date).
Otherwise:
MPTEXPRE
environment variable exists (`mptexpre.tex' by default), that file
is prepended to the input from the MetaPost file.
If any of the above steps fail, for example if there was a typesetting mistake in the original mpfile, output may be left in files named `mpxerr.{log,tex,dvi}' (TeX) or `mpxerr{,.t}' (Troff), so you can diagnose the problem.
The `-troff' option to MPto selects the Troff commands, rather than TeX. MetaPost supplies this automatically if the `-T' or `-troff' option was specified to MetaPost.
The MPX file created by MakeMPX is a sequence of MetaPost picture expressions, one for every label in the original MetaPost input file.
The names of the commands run by MakeMPX, and the directory
added to the shell search PATH for the commands' location, are
overridden by environment variables. Here is a list:
MAKEMPX_BINDIR
PATH. Default is the `$(bindir)'
Make directory, which in turn is set from the configure-time
`--bindir', `--exec-prefix' and `--prefix' options; if
nothing else is specified, the default is file `/usr/local'.
NEWER
MPTOTEX
MPTOTR
DVITOMP
DMP
TEX
latex, and supply an appropriate
verbatimtex header in the MP source (see section 6.1 mpost invocation).
TROFF
TRFONTS
environment variable or configuration value to point to the appropriate
font directory, traditionally `/usr/lib/font/devterm'.
DVItoMP converts DVI files into low-level MetaPost commands in a so-called MPX file. This program is generally invoked only by MakeMPX (see section 6.4 MakeMPX: Support MetaPost labels). Synopsis:
dvitomp dvifile[.dvi] [mpxfile[.mpx]]
If mpxfile is not specified, the output goes to the basename of dvifile extended with `.mpx', e.g., `dvitomp /wherever/foo.dvi' creates `./foo.mpx'.
The only options are `-help' and `-version' (see section 3.2 Common options).
DMP converts device-independent Troff (ditroff) output files into low-level MetaPost commands in a so-called MPX file. This program is generally invoked by MakeMPX (see section 6.4 MakeMPX: Support MetaPost labels). Synopsis:
dmp [ditroff-file [mpxfile]]
If ditroff-file is not specified, input comes from standard input; and if mpxfile is not specified, output goes to standard output.
DMP was written to process the output of a Troff pipeline fed the output
of mpto -troff (see section 6.7 MPto: Extract labels from MetaPost input). DMP understands all
the `Dc' graphics functions that dpost does, but it
ignores `x X' device control functions such as `x X
SetColor:...', `x X BeginPath:', and `x X
DrawPath:...'.
The available font names are defined in the support file
`trfonts.map', which DMP looks for along the MPSUPPORT path.
Another support file `trchars.adj', also looked for along the
MPSUPPORT path, contains a character adjustment table which
should reflect the shift amounts found in the standard PostScript
prologue for Troff and dpost found in the TRFONTS directory.
Such an adjustment table is unnecessary for some Troff implementations,
in which case `trchars.adj' should be replaced by an empty
file--but it must still exist.
DMP was written for one particular Troff implementation, and it unfortunately has many built-in assumptions about the output and fonts file formats used by Troff, which may not be satisfied in other environments. In particular, GNU groff uses some extensions in its file formats described in groff_font(5) and groff_out(5) which make its output completely unusable for DMP. On the other hand, the Troff version found in Sun Solaris 2.x, and perhaps other systems derived from System V R4, works fine with the default settings.
If you run into trouble and want to adapt DMP to other systems, you might have to try the following (this is primarily for hackers):
TROFF environment variable appropriately (see above). Also,
locate the appropriate font directory and set the TRFONTS
variable as needed.
(Some of the above description was edited from the `dmp.c' source file, written by John Hobby.)
The only options are `--help' and `--version' (see section 3.2 Common options).
MPto extracts the labels from a MetaPost input file; this is the
contents of any btex...etex and verbatimtex...etex
sections. This program is generally invoked by MakeMPX (see section 6.4 MakeMPX: Support MetaPost labels). Synopsis:
mpto [option]... mpfile
The input comes from mpfile; no path searching is done. The output goes to standard output. Leading and trailing spaces and tabs are removed, and various predefined typesetter commands are included at the beginning of and end of the file and of each section.
The program accepts the following options, as well as the standard `-help' and `-version' (see section 3.2 Common options):
Newer compares file modification times. Synopsis:
newer src dependent
Newer exits successfully if the file src exists and is older as dependent, i.e., the modification time (mtime) of src is greater than that of dependent. See section `Attribute Meanings' in GNU C Library.
Although this could be written as a Perl script (see section `File Operations' in Perl) or using the `--full-time' option
supported by ls (see section `ls invocation' in GNU file utilities), it seems undesirable to depend on such independent, and
sadly non-universal, programs.
This is used by MakeMPX (see section 6.4 MakeMPX: Support MetaPost labels).
Go to the first, previous, next, last section, table of contents.