MPOST(1)MPOST(1)NAME
mpost, inimpost, virmpost - MetaPost, a system for drawing
pictures
SYNOPSISmpost [options] [commands]
DESCRIPTION
This manual page is not meant to be exhaustive. The com-
plete documentation for this version of TeX can be found
in the info file or manual Web2C: A TeX implementation.
MetaPost interprets the MetaPost language and produces
PostScript pictures. The MetaPost language is similar to
Knuth's Metafont with additional features for including
tex(1) or troff(1) commands and accessing features of
PostScript not found in Metafont.
Like TeX and Metafont, MetaPost is normally used with a
large body of precompiled macros. This version of Meta-
Post looks at its command line to see what name it was
called under. Both inimpost and virmpost are symlinks to
the mpost executable. When called as inimpost (or when
the --ini option is given) it can be used to precompile
macros into a .mem file. When called as virmpost it will
use the plain mem. When called under any other name,
MetaPost will use that name as the name of the mem to use.
For example, when called as mpost the mpost mem is used,
which is identical to the plain mem. Other mems than
plain are rarely used.
The commands given on the command line to the program are
passed to it as the first input line. (But it is often
easier to type extended arguments as the first input line,
since UNIX shells tend to gobble up or misinterpret Meta-
Post's favorite symbols, like semicolons, unless you quote
them.) The first line should begin with a filename, a
\controlsequence, or a &memname.
The normal usage is to say mpost figs to process the file
figs.mp. The basename of figs becomes the ``jobname'',
and is used in forming output file names. If no file is
named, the jobname becomes mpout. The default extension,
.mp, can be overridden by specifying an extension explic-
itly.
There is normally one output file for each picture gener-
ated, and the output files are named jobname.nnn, where
nnn is a number passed to the beginfig macro. The output
file name can also be jobname.ps if this number is nega-
tive.
The output files can be used as figures in a TeX document
by including
\special{psfile=jobname.nnn}
in the TeX document. Alternatively, one can \input
epsf.tex and then use the macro
\epsfbox{jobname.nnn}
to produce a box of the appropriate size containing the
figure.
btex TeX commands etex
This causes mpost 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 \vbox or a minipage environ-
ment.
verbatimtex TeX commands etex
This is ignored by mpost except that the TeX com-
mands are passed on to TeX. When using LaTeX
instead of TeX the input file must start with a
verbatimtex block that gives the \documentstyle and
\begin{document} commands. You can use the `%&'
construct in the first verbatimtex block to ensure
that the correct TeX format is used to process the
commands.
Since most TeX fonts have to be downloaded as bitmaps, the
btex feature works best when the output of mpost is to be
included in a TeX document so that dvips(1) can download
the fonts. For self-contained PostScript output that can
be used directly or included in a troff document, start
your MetaPost input file with the command prologues:=1 and
stick to standard PostScript fonts. TeX and MetaPost use
the names in the third column of the file trfonts.map,
which can be found in the directories with support files
for MetaPost.
MetaPost output can be included in a troff document via
the -m pictures macro package. In this case mpost should
be invoked with the -T flag so that the commands between
btex and etex or between verbatimtex and etex are inter-
preted as troff instead of TeX. (This automatically sets
prologues:=1 ).
OPTIONS
This version of MetaPost understands the following command
line options.
--file-line-error-style
Print error messages in the form file:line:error
which is similar to the way many compilers format
them.
--help Print help message and exit.
--ini Be inimpost, for dumping bases; this is implicitly
true if the program is called as inimpost.
--interaction mode
Sets the interaction mode. The mode can be one of
batchmode, nonstopmode, scrollmode, and errorstop-
mode. The meaning of these modes is the same as
that of the corresponding commands.
--jobname name
Use name for the job name, instead of deriving it
from the name of the input file.
--kpathsea-debug bitmask
Sets path searching debugging flags according to
the bitmask. See the Kpathsea manual for details.
--mem mem
Use mem as the name of the mem to be used, instead
of the name by which MetaPost was called or a %&
line.
--parse-first-line
If the first line of the main input file begins
with %& parse it to look for a dump name or a
--translate-file option.
--progname name
Pretend to be program name. This affects both the
format used and the search paths.
--recorder
Enable the filename recorder. This leaves a trace
of the files opened for input and output in a file
with extension .fls.
-T Produce TROFF output.
--translate-file tcxname
Use the tcxname translation table.
--troff
As -T.
--version
Print version information and exit.
ENVIRONMENT
See the Kpathsearch library documentation (the `Path spec-
ifications' node) for the details of how the environment
variables are use when searching. The kpsewhich utility
can be used to query the values of the variables.
If the environment variable TEXMFOUTPUT is set, MetaPost
attempts to put its output files in it, if they cannot be
put in the current directory.
Here is a list of the environment variables affect the
behavior of mpost:
MPINPUTS
Search path for input files.
MFINPUTS
Auxiliary search path for input files with
.mf extensions.
MPSUPPORT
Directory for various tables for handling
included tex and troff.
MPXCOMMAND
The name of a shell script that converts
embedded typesetting commands to a form that
MetaPost understands. Defaults: makempx for
tex and troffmpx for troff.
TEX The version of TeX - or LaTeX - to use when
processing btex and verbatimtex commands.
Default tex. This version of MetaPost
allows you to use a `%&format' line instead.
TROFF The troff pipeline for btex and verbatimtex
commands. Default eqn -d\$\$ | troff
MPEDIT A command template for invoking an editor.
A .mem file is a binary file that permits fast
loading of macro packages. mpost reads the default
plain.mem unless another .mem file is specified at
the start of the first line with an & just before
it. There is also an mfplain.mem that simulates
plain Metafont so that mpost can read .mf fonts.
(Plain Metafont is described in The Metafontbook).
Experts can create .mem files be invoking inimpost
and giving macro definitions followed by a dump
command.
The MetaPost language is similar to Metafont, but
the manual A User's Manual for MetaPost assumes no
knowledge of Metafont. MetaPost does not have
bitmap output commands or Metafont's online display
mechanism.
FILES
mpost.pool
Encoded text of MetaPost's messages.
*.mem Predigested MetaPost mem files.
plain.mp
The standard mem file.
mfplain.mp
The Metafont-compatible mem file. This is
loaded when virmp is invoked via a symbolic
link as mfmp.
$TEXMFMAIN/metapost/base/*.mp
The standard MetaPost macros included in the
original distribution.
$TEXMFMAIN/metapost/support/*
Various tables for handling included tex and
troff.
$TEXMFMAIN/metapost/support/trfonts.map
Table of corresponding font names for troff
and PostScript.
psfonts.map
Table of corresponding font names for tex
and PostScript.
$TEXMFMAIN/doc/metapost/examples.mp
The source file for a few sample figures
that are part of a LaTeX document $TEXMF-
MAIN/doc/metapost/mpintro.tex that describes
the MetaPost system in a little more detail.
SUGGESTED READING
Donald E. Knuth, The Metafontbook (Volume C of Com-
puters and Typesetting), Addison-Wesley, 1986, ISBN
0-201-13445-4.
John D. Hobby, A User's Manual for MetaPost, CSTR
162, AT&T Bell Labs,
John D. Hobby, Drawing Graphs with MetaPost, CSTR
164, AT&T Bell Labs,
TUGboat (the journal of the TeX Users Group).
SEE ALSOtex(1), mf(1), dvips(1).
AUTHORS
MetaPost was designed by John D. Hobby, incorporat-
ing algorithms from Metafont by Donald E. Knuth.
It was originally implemented on Unix, incorporat-
ing system-dependent routines from web2c, while not
relying on it except for the actual Web-to-C trans-
lator.
Ulrik Vieth adapted MetaPost to take advantage of
the advanced path searching features in more recent
versions of web2c and worked towards fully inte-
grating MetaPost into the canonical Unix TeX dis-
tribution. He also updated and extended this man-
ual page.
TRIVIA
Unlike TeX and Metafont, MetaPost originally didn't
use any fancy logo. John Hobby says he prefers the
spelling ``MetaPost'', yet Don Knuth has updated
the Metafont logo.mf font to be able to typeset a
proper MetaPost logo similar to the Metafont logo.
Feel free to use whatever you think is more appro-
priate!
Web2C 7.4.5 10 November 2001 MPOST(1)
