%%% File: instruct.txt
%%% A part of mfpic 0.6b 2003/01/02
%%%

This is an beta-test version of mfpic.

See manifest.txt for a list of files and a brief description of each.

Files Required
--------------
In a minimal installation only mfpic.tex is required by TeX or LaTeX,
grafbase.mf for Metafont, grafbase.mp and dvipsnam.mp for MetaPost. The
file mfpic.sty merely inputs mfpic.tex. It allows for use in the LaTeX
\usepackage command. The rest of the .tex files are documentation and
test files.

-- Install mfpic.tex where TeX will find it, mfpic.sty where LaTeX will
   find it. On any TDS compliant system (such as teTeX, fpTeX, TeXLive,
   or MiKTeX) they can be put in $TEXMF/tex/generic/mfpic/ (where $TEXMF
   indicates a directory serving as a root of a texmf tree).
-- Install All .mp files (grafbase.mp and dvipsnam.mp) where MetaPost
   will find them, for example $TEXMF/metapost/mfpic/ .
-- Install grafbase.mf where Metafont will find it. For example,
   $TEXMF/metafont/mfpic/ .
-- If required by your TeX system, UPDATE THE FILENAME DATABASE.

Please process the documentation mfpicdoc.tex and the supplement
mppicdoc.tex (run plain TeX on them, making sure header.tex,
indexing.tex and mfpicdoc.ind are where TeX will find them), and read
them before trying anything further. If you are familiar with mfpic,
version 0.2.10.9 or later, you can probably get going right away, or
after reading mppicdoc.tex for MetaPost specific info (except for
several new commands).

The remaining instructions here are about using mfpic with MetaPost,
assuming you have used mfpic with Metafont before.

In order to turn on MetaPost support you put something like this in your
file.tex (plain TeX, plain pdfTeX or LaTeX209):
   +-----------------------+
   | \input mfpic          |
   | \usemetapost          |
   | \opengraphsfile{figs} |
   +-----------------------+
or in LaTeX2e or pdfLaTeX:
   +------------------------------+
   | \usepackage[metapost]{mfpic} |
   | \opengraphsfile{figs}        |
   +------------------------------+

Using mfpic with MetaPost
-------------------------
For the most part, mfpic with MetaPost support is used just like mfpic
with Metafont, but instead of running a combination of Metafont and
gftopk on the output .mf file, one uses Metapost on the output .mp file.
That is:

1) Run the appropriate TeX on your file.tex. A file figs.mp is produced.
2) Run "mpost figs" (or "mp figs" on some systems). This creates files
   figs.1, figs.2, etc., one for each mfpic environment.
3) Run TeX again, this resolves bounding box information and includes
   the eps figures.
4) Process with an appropriate dvi-to-whatever processor that supports
   .eps or MetaPost figure inclusions. (Omitted for pdf(La)TeX)

For this to work out of the box with plain TeX and LaTeX209 you need
epsf.tex (normally distributed with dvips), for pdfTeX and pdfLaTeX you
need supp-mis.tex and supp-pdf.tex (often distributed with pdftex, these
are part of the ConTeXt system, CTAN/macros/context/cont-tmf.zip), and
for LaTeX2e you need the graphics package plus (for pdfLaTeX) a
reasonably recent version of pdftex.def and a config file graphics.cfg
that can detect pdfLaTeX. The graphics package is in most TeX
distributions, or can be found in CTAN/macros/latex/required/graphics/

The file epsf.tex officially supports only dvips, but many dvi-to-
whatever software that can handle eps inclusions will also work with it.
If your system happens not to be compatible with epsf.tex, and you need
to use plain TeX, you will need to \input the appropriate macro files,
and redefine \setmfpicgraphic and \getmfpicoffset to the appropriate
graphic inclusion command. See mppicdoc.tex.

The syntax of the mfpic environments has _not_ changed. You still type
"\mfpic" or "\begin{mfpic}" to start a picture, and \lines{(0,0),(1,1)}
to draw a line, for example. There are a few new commands, and some old
commands now take optional arguments (see mfpicdoc and mppicdoc), but
these are, well, optional. On the other hand, any old \mfsrc hacks are
almost certainly doomed to failure, as grafbase.mp is quite different
from grafbase.mf.

Compatibility
-------------
This version is intended to be backward compatible with versions
0.2.10.9 or later in the sense that old files can still be processed
without change. The following should all work (within limits, in
particular nothing is likely to work for hacks that used \mfsrc):

1) Running MetaPost on old .mf files created with mfpic 0.2.10.9 or
   later. Unless you hacked about with \mfsrc, this _should_ create
   _some_ sort of picture without error messages (assuming none occurred
   before). Postscript is a little more sensitive to the order of
   drawing, so things might not look quite the same (see mppicdoc). On
   the other hand, sometimes they look better. Please let us know if you
   try this and anything goes wrong that you think should not.

2) Using \input mfpic _without_ \usemetapost. This will create a
   Metafont file, not the same file as before but it should be
   possible to run either Metafont + gftopk, or MetaPost on the result.
   In fact, some bugs have been removed (but maybe some have been added,
   too). You could try this in old files (that used mfpic 0.2.10.9 or
   later). If you do try this, please let us know if anything goes
   wrong.

3) Adding \usemetapost to old files (using mfpic 0.2.10.9 or later).
   Things should work (except for \mfsrc commands), but just as in (1)
   above, Postscript can be more sensitive to the order of drawing.
   Again, please report any problems.

Do _not_ run MetaFONT on figs.mp. Also, make sure MetaPost can find
grafbase.mp, otherwise it may try to input grafbase.mf.  This will never
succeed.

Actually, two incompatibilities have been introduced. If you use
\savepic{\foo} to save an mfpic-ture for later use, you must now first
allocate the storage bin with \newsavepic{\foo} (analogous to the LaTeX
\savebox-\newsavebox scheme). In LaTeX2e documents, inputting mfpic.tex
after \begin{document} will produce an error (due to LaTeX preamble-only
commands like \ProvidesPackage).

Let us know the good as well as the bad results you have.

Where?
------
The latest test versions of this distribution should be available
at <a href="http://comp.uark.edu/~luecking/tex/mfpic.html">my web site</a>.

--
Dan Luecking      email: luecking@uark.edu
Department of Mathematical Sciences
University of Arkansas
Fayetteville, Arkansas 72701-1201
U.S.A
