%%% File: instruct.txt
%%% A part of mfpic 0.5.0 2001/10/30
%%%

This is a beta-test version of mfpic.

See manifest.txt for a list of files and a brief description of each.
The main new feature added with 0.4.0 was support for production and
inclusion of MetaPost graphics. The new features added with 0.5.0 are
outlined in the file whats.new.

Files Required
--------------
In a minimal installation only mfpic.tex is required by TeX or LaTeX,
grafbase.mf for Metafont, and grafbase.mp plus 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.

-- mfpic.tex goes where TeX will find it, mfpic.sty where LaTeX will
   find it. On my system I put both in /localtexmf/tex/generic/mfpic/ .
-- All .mp files (grafbase.mp and dvipsnam.mp) go where MetaPost will
   find them. On my system, I use /localtexmf/metapost/grafbase/ .
---The file grafbase.mf goes where Metafont will find it. On my system,
   /localtexmf/metafont/grafbase/ .

If your system uses a filename database, update that after copying the
files to the correct location. (For example, run texhash in tetex or
initexmf -u in MiKTeX.)

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

Test your installation
----------------------
1. Put the example file pictures.tex in the current directory and run
     tex pictures.tex
   or
     latex lapictures.tex
2. Then run
     mf pics.mf
   creating pics.tfm and pics.720gf (the number may be something else).
3. Then run
     gftopk pics.720gf pics.pk
4. Rerun tex or latex
5. View the result.

What could go wrong
-------------------
If step 1 fails: check that you have pictures.tex or
lapicture.tex in the current directory. Make sure your latex is
reasonably new. Make sure there is no earlier version of mfpic.tex in
TeX's search path. Make sure there is no pics.tfm in the TeX search
path.

If step 2 fails: Make sure that pics.mf was indeed created by the tex
step in the current directory. Make sure grafbase.mf (and no earlier
version) is in Metafont's search path. It is possible mf may complain
about "localfont", if so try using the command
    mf \mode:=ljfour; input pics.mf
(on some systems you may need to "quote" or "escape" parts of the
command line) replacing "ljfour" by the Metafont mode for your printer.
If you have a properly configured dvips, you should find the correct
mode name in the file config.ps in a line beginning with "M", like
    M jetiiisi
Alternatively, find the file modes.mf and edit the following line (or
add it) at the end:
    localfont:=ljfour;
using the same mode name in place of ljfour. Then ask your system to
remake plain.base.

If step 3 fails, find the proper command or syntax for your system.

If step 4 fails, make sure there is no pics.tfm in the locations TeX
searches for .tfm files (except the pics.tfm you just created in the
current directory). Make sure pics.tfm was created and that TeX looks in
the current directory for .tfm files.

If step 5 fails, make sure your system looks in the current directory
for .tfm and .pk files. Make sure there is no pics.pk already in your
viewer's search path except the one in the current directory.

Using mfpic with MetaPost
-------------------------
You may prefer to create figures as EPS files with MetaPost instead of
making a font with Metafont.

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 and pdfLaTeX you need the graphics package (using the
pdftex option with pdfLaTeX). The graphics package is in most TeX
distributions, or can be found in CTAN/macros/latex/required/graphics/ .

The file epsf.tex supports only dvips \special s, but many dvi-to-whatever
software that can handle eps inclusions will accept these. 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 to the appropriate file inclusion command. See
mppicdoc.tex.

The sequence of steps to test this is:
0. Edit pictures.tex or lapictures.tex, adding the line
     \usemetapost
   after the line \input mfpic (or \usepackage{mfpic})
1. Run
     tex pictures.tex
     OR pdftex pictures.tex
     OR latex lapictures.tex
     OR pdflatex lapictures.tex
   creating pics.mp
2. Run
     mpost pics.mp
3. Rerun (pdf){la}tex.
4. For (la)tex, run dvips on pictures.dvi to create pictures.ps and
   view with a postscript viewer like gsview. For pdf(la)tex, view
   (la)pictures.pdf with Acrobat or other PDF viewer.

What could go wrong
-------------------
Generally the only thing that could go wrong with this test is the
non-existence of one of the support packages mentioned above in the
appropriate search path, or an incorrect version or misconfiguration of
such. Or the failure of one of the programs used to look in the current
directory.

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

This version is intended to be compatible with files that used 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) Old .mf files created with mfpic 0.2.10.9 or later. It should be
   possible to run either mf or mpost on these and the latter _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.

2) Old .tex files which \input the new mfpic: Running tex on these
  (unedited) should create a .mf file, not the same file as before, but
  it should be possible to run either mf, or mpost 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 .tex files that used mfpic 0.2.10.9 or
   later: Things should work, but just as in (1) above, Postscript can
   be more sensitive to the order of drawing.

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.

One incompatibility has 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).

Old .tex files that relied on certain undocumented features may be
incompatable with the current mfpic.

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
