Go to the first, previous, next, last section, table of contents.


6. MetaPost: Creating technical illustrations

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.

6.1 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).

The MetaPost construct

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):

`-kpathsea-debug=number'
`-ini'
`-mem=memname'
`-progname=string'
`-translate-file=tcxfile'
These options are common to TeX, Metafont, and MetaPost. See section 3.2 Common options.
`-T'
`-troff'
Set the prologues internal variable to 1, and use makempx -troff to generate MPX files.
`-tex=texprogram'
When this option is given, the program texprogram is used to typeset the labels.

6.2 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).

6.3 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.

6.4 MakeMPX: Support MetaPost labels

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:

  1. MPto is run to extract the label text from the MetaPost source file mpfile (see section 6.7 MPto: Extract labels from MetaPost input).
  2. The typesetting program itself is run, either TeX or Troff (see below). If TeX, and the file named by the MPTEXPRE environment variable exists (`mptexpre.tex' by default), that file is prepended to the input from the MetaPost file.
  3. The typesetter output (a DVI file in the case of TeX, Ditroff output for Troff) is translated back to MetaPost, by DVItoMP (see section 6.5 DVItoMP: DVI to MPX conversion) or DMP (see section 6.6 DMP: Ditroff to MPX conversion) respectively.

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
The directory added to the 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
The command run to determine if mpxfile is out of date with respect to mpfile; default is `newer'.
MPTOTEX
The command run to extract MetaPost labels in TeX format; default is `mpto -tex'.
MPTOTR
Likewise, for Troff; default is `mpto -troff'.
DVITOMP
The command run to convert TeX output back to MetaPost; default is `dvitomp'.
DMP
Likewise, for Troff; default is `dmp'.
TEX
The command run to typeset the labels in TeX; default is `tex'. If you use LaTeX, set this to latex, and supply an appropriate verbatimtex header in the MP source (see section 6.1 mpost invocation).
TROFF
Likewise, for Troff; default is `'eqn -d\$\$ | troff -Tpost''. You may need to replace `-Tpost' by `-Tterm', where term is the PostScript device name for your Troff implementation, e.g., `ps' or `psc'; see troff(1). If you change this, you will also need to set the TRFONTS environment variable or configuration value to point to the appropriate font directory, traditionally `/usr/lib/font/devterm'.

6.5 DVItoMP: DVI to MPX conversion

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).

6.6 DMP: Ditroff to MPX conversion

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):

(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).

6.7 MPto: Extract labels from MetaPost input

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):

`-troff'
Surround the MetaPost sections with Troff commands.
`-tex'
Surround the MetaPost sections with TeX commands. This is the default.

6.8 Newer: Compare file modification times

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.