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

MetaPost: Creating technical illustrations

MetaPost is a picture-drawing language similar to Metafont (see section 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 tex invocation, and see section 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 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 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 tex invocation.

The program accepts the following options, as well as the standard `-help' and `-version' (see section Common options):

`-kpathsea-debug=number'
`-ini'
`-mem=memname'
`-progname=string': These options are common to TeX, Metafont, and MetaPost. See section Common options.
`-T'
`-troff': Set the 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 Memory dumps). For a detailed comparison of virgin and initial forms, see section Initial and virgin.

For a list of options and other information, see section mpost invocation.

The only memory dump file commonly used with MetaPost is the default, `plain.mem', also known as `mpost.mem' (again, see section 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 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 Initial and virgin.

For a list of options and other information, see section mpost invocation.

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:

MPto is run to extract the label text from the MetaPost source file mpfile (see section MPto: Extract labels from MetaPost input).
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.
The typesetter output (a DVI file in the case of TeX, Ditroff output for Troff) is translated back to MetaPost, by DVItoMP (see section DVItoMP: DVI to MPX conversion) or DMP (see section 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 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'.

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

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

If DMP complains about a missing font table (e.g., `Cannot find TR'), your Troff may not support the device `post'. Check troff(1) for the devices supported by your Troff and set the TROFF environment variable appropriately (see above). Also, locate the appropriate font directory and set the TRFONTS variable as needed.
If DMP complains about a missing font description file (e.g., `Font TR was not in map file'), your version of Troff may be using internal font names different from those in the distributed `trfonts.map'; e.g., TR and TI instead of R and I for Times-Roman and Times-Italic. In this case, you may have to adapt `trfonts.map' and perhaps also `trchars.adj' in the MetaPost support directory (`texmf/metapost/support' by default).
If DMP still complains that it cannot parse the font description files or the Troff output (e.g., `TR has a bad line in its description file', you are probably out of luck and have to hack the DMP program (in `web2c/mpware/dmp.c'). Such problems may be caused by subtle differences in the file formats, such as use of tabs vs. spaces as field separators or decimal vs. octal vs. hex format for font metric data. A reasonably good description of the expected Troff file formats can be found in AT&T technical report CSTR-54 (Troff User's Manual, Revised 1992). Documentation on the subtle differences in other Troff implementation is harder to find except for GNU groff, where it's all documented in the above-mentioned groff_font(5) and groff_out(5). Any contributions to improve the portability of DMP or to make it work with GNU groff are welcome, of course.

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

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

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

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 MakeMPX: Support MetaPost labels).

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