(web2c.info)mpost invocation

---

Next: Initial MetaPost Up: MetaPost

---

Enter node , (file) or (file)node

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 in
'TEXMF/doc/metapost/', where TEXMF is the root of TeX directory
structure.  See also:
   * <http://cm.bell-labs.com/who/hobby/MetaPost.html> (the MetaPost
     author's home page);
   * <http://tug.org/metapost> (papers, packages, and related
     information).

   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 (Note: 'tex'
invocation, and Note: 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
(Note: (kpathsea)Supported file formats), 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' (Note: (dvips)EPSF macros).

   The MetaPost construct
     btex ... TEX-INPUT ... etex
generates a MetaPost picture expression corresponding to TEX-INPUT.

   The construct
     verbatimtex ... TEX-INPUT ... etex
simply passes the TEX-INPUT through 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'.

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

   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
(Note: (dvips)Fonts in figures).  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
(*note (dvips)psfonts.map::).

   It is posible for pdfTeX to read MetaPost output directly; this is in
contrast to general EPSF files, which have to be converted for use with
PDF output.  The easiest way is to name the MetaPost output files with
the '.mps' extension.  Then the LaTeX '\includegraphics' command, for
example, will be able to read them, even when outputting PDF.

   MetaPost can write output files, via the 'write' primitive; this
opens a security hole.  Note: tex invocation.

   The program accepts the following options, as well as the standard
'-help' and '-version' (Note: Common options):
'-[no]-file-line-error'
'-fmt=FMTNAME'
'-halt-on-error'
'-ini'
'-interaction=STRING'
'-jobname=STRING'
'-kpathsea-debug=NUMBER'
'-[no]parse-first-line'
'-output-directory'
'-progname=STRING'
'-recorder'
'-translate-file=TCXFILE'
'-8bit'
     These options are common to TeX, Metafont, and MetaPost.  Note:
     Common options.

'-T'
'-troff'
     Set the 'prologues' internal variable to '1'.

'-tex=TEXPROGRAM'
     When this option is given, the program TEXPROGRAM is used to
     typeset the labels.