MPOST(1)                                                 MPOST(1)

NAME
       mpost, inimpost, virmpost - MetaPost, a system for drawing
       pictures

SYNOPSIS
       mpost [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 mp 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  mp  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 mp except that the TeX commands
              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{doc-
              ument} commands.  You can use the `%&' construct in
              the first verbatimtex block to ensure that the cor-
              rect 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  mp  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 mp should be
       invoked with the -T flag so that the commands between btex
       and  etex  or between verbatimtex and etex are interpreted
       as troff instead of TeX.  (This  automatically  sets  pro-
       logues:=1 ).

OPTIONS
       This version of MetaPost understands the following command
       line options.

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

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

       --kpathsea-debug bitmask
              Sets path searching debugging  flags  according  to
              the  bitmask.  See the Kpathsea manual for details.

       --progname name
              Pretend to be program name.  This affects both  the
              format used and the search paths.

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

       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 under-
              stands.  Defaults: makempx for tex and troffmpx for
              troff.

       TEX    The version of TeX - or LaTeX - to  use  when  pro-
              cessing  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 com-
              mands.  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 that sim-
       ulates 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 man-
       ual  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 origi-
              nal 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   $TEXMFMAIN/doc/meta-
              post/mpintro.tex that describes the MetaPost system
              in a little more detail.

SUGGESTED READING
       Donald E. Knuth, The Metafontbook (Volume C  of  Computers
       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 ALSO
       tex(1), mf(1), dvips(1).

AUTHORS
       MetaPost was designed  by  John  D.  Hobby,  incorporating
       algorithms from Metafont by Donald E. Knuth.  It was orig-
       inally implemented on Unix, incorporating system-dependent
       routines  from  web2c, while not relying on it exccept for
       the actual Web-to-C translator.

       Ulrik Vieth adapted MetaPost  to  take  advantage  of  the
       advanced  path  searching features in more recent versions
       of web2c and worked  towards  fully  integrating  MetaPost
       into the canonical Unix TeX distribution.  He also updated
       and extended this manual 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 approporiate!

Web2C 7.3                 29 March 1999                         1