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.

- mpost invocation: Invoking MetaPost.
- inimpost invocation: Initial MetaPost.
- virmpost invocation: Virgin MetaPost.
- makempx invocation: Create MPX files for labels.
- dvitomp invocation: DVI-to-MPX translation.
- dmp invocation: Ditroff-to-MPX translation.
- mpto invocation: Extracting labels from MetaPost programs.
- newer invocation: Is one file newer than another?

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

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