path: root/Master/texmf-dist/doc/generic/mfpic/README

%%% File: README.txt
%%% A part of mfpic 0.7a beta 2004/04/16
%%%

MFpic defines a command group \mfpic...\endmfpic (optionally in LaTeX
an environment, mfpic) and drawing commands to be used inside this group.
When TeX (or LaTeX) is run on a file containing those commands, a
Metafont (or MetaPost) source file is created. When that file is correctly
processed by Metafont (or MetaPost), and LaTeX or TeX is run again, the
result is a figure in the TeX document in the location of each
environments.

See install.txt for initial setup and brief installation instructions.
See mfpguide.pdf for a short tutorial. See below for a summary of
features added since the previous official release (0.6c beta). See the
manual mfpman.pdf for more detailed instructions and descriptions
of features.

This is mfpic version 0.7a beta.

LEGALITIES
----------

All files of the core mfpic distribution (listed below) may be
distributed and/or modified under the conditions of the LaTeX Project
Public License, either version 1.2 of this license or (at your option)
any later version. The latest version of this license is in
  http://www.latex-project.org/lppl.txt
and version 1.2 or later is part of all distributions of LaTeX version
1999/12/01 or later.

While every effort has been made to make mfpic useful, it comes with no
warranty, expressed or implied.


MANIFEST
--------

Here is a list, plus explanation of purpose, of all files in the mfpic
distribution. Read it *before* trying to process any of the example
files. These, and the files generated by TeXing mfpic.ins, constitute
the mfpic distribution to which the LPPL applies.

The three files marked with * below are the only ones essential
for using all the facilities of mfpic.

All the *.tex files in the src directory (except the plainTeX file
refcard.tex) require the LaTeX style file mfpdoc.sty. The manual is
mfpman.pdf.

TeX/LaTeX code:
--------------
*mfpic.dtx           Contains mfpic.sty and mfpic.tex
*mfpic.ins           The unpacking script, run latex on it. It reads in
                     mfpic.dtx and grafbase.dtx and produces the only
                     required files: mfpic.sty, mfpic.tex, grafbase.mf,
                     grafbase.mp, and dvipsnam.mp

MetaPost/Metafont code:
----------------------
*grafbase.dtx        Contains grafbase.mf, grafbase.mp and dvipsnam.mp

Documentation:
-------------

 install.txt          Basic information on installation
 README.txt           This file.
 changes.txt          Rambling history of (most) changes
 mfpguide.pdf         Precompiled tutorial
 mfpman.pdf           Precompiled manual
 src/refcard.tex      reference card, landscape, should fit on two sides
                      of either USletter or A4paper. Plain TeX source.
 src/mfpdoc.sty       LaTeX style used by the next two
 src/mfpguide.tex     tutorial (LaTeX source, requires mfpdoc.sty and mfpic)
 src/mfpman.tex       manual (LaTeX source, requires mfpdoc.sty)

 examples/pictures.tex    Run tex, produce pics.mf file
 examples/lapictures.tex  Run latex, produce pics.mf file (same)
 examples/data.dat        External data file needed for above two
 examples/forfun.tex      Example of \mfsrc: Run tex, produce forfun.mp


NEW FEATURES since Version 0.6c
-------------------------------
  -- Mfpic is now distribution in two .dtx files and an unpacking
     script (mfpic.ins). The manual is now supplied as a linked PDF file
     written in LaTeX. A short introductory guide is supplied, also PDF.

  -- New path modification commands that produce a subpath of a
     given path:
     \partpath{<frac1>,<frac2>}<path>
         The arguments are fractions of the length of <path> indicating
         where the subpath begins and ends.
     \subpath{n,m}<path>
         {n,m} are the `times' on <path> where the subpath begins and
         ends. (See the Metafontbook for the meaning of `time'.)
     \cutoffbefore{X}<path>
         X is a symbolic name for a path previously defined using \store.
         The subpath produced begins where X and <path> first intersect,
         and ends where <path> ends.
     \cutoffafter{X}<path>
         Similar to \cutoffafter but starts where <path> starts and ends
         where X and <path> _last_ intersect.
     \trimpath{<dim1>,<dim2>}<path>
         The dimensions are the lengths trimmed from the start and end
         of the following path.

  -- Color commands now work under Metafont in the sense that no errors
     or even warnings are caused by the commands that set and change
     colors, and moreover, \draw[white]<path>. will erase the pixels
     along <path> and \gfill[<color>]<closed path> will attempt to convert
     the color to a shade of gray and approximate that by filling with a
     pattern of pixels. All the following: \draw, \dashed, \dotted,
     \plot, \plotnodes, all hatching commands, \point and \plotsymbol are
     limited to black and white. \gfill and \polkadot will produce
     shades of gray if the color is not black or white. filling (or
     polkadotting) with white will erase pixels.

     For this to work, bare MetaPost color triples should not be used,
     but only color functions (e.g., rgb(1,.5,0)) or names defined with
     \mfpdefinecolor. The colors defined in dvipsnam.mp are not
     recognized by Metafont.

  -- New color setting command, \pointcolor. The \point and \plotsymbol
     commands now draw in the color set with \pointcolor. (In Metafont
     this can be black or white.)

  -- The dashpatterns, colors, and symbols used by the \plotdata command
     for different curves can be reconfigured by the user with
       \reconfigureplot {dashes}{<list>},
       \reconfigureplot {colors}{<list>}, and
       \reconfigureplot{symbols}{<list>},
     where <list> is a comma separated list of dash patterns, colors, or
     symbols. The builtin defaults can be restored with
     \defaultplot{dashes}, etc.

  -- \circle now accepts an optional argument similar to \arc that
     allows one to define the circle in different ways. For example,
     \circle[t]{<p1>,<p2>,<p3>}, will draw the circle that passes
     through the three given points.

  -- For those curve creation commands that accept an optional tension
     argument, the default (= 1) can be changed with the command
     \settension. The affected commands are \curve, \cyclic, \function,
     \plrfcn, \datafile, \plotdata, \bclosed, \sclosed, \btwnfcn,
     \plrregion, \fcncurve, \mfbezier, and \closedmfbezier.

  -- The closure commands \bclosed and \sclosed now accept an optional
     argument for the tension to be used in the closing link. The
     commands \sclosed\curve and \cycle have always produced the same
     path. Now the same is true when tension is used:
     \sclosed[1.5]\curve[1.5] = \cycle[1.5] The default tension is the
     same as for \curve.

  -- The commands to surround text with a path (\tlabelrect, \tlabeloval
     and \tlabelellipse) now accept a second optional argument that
     is the same as that taken by \tlabel for justification/rotation of
     the text. In order to use it, the first optional argument must be
     present (though it may be empty to select the default). The
     preloaded default for this new argument is [cc]. This can be
     changed with \tlpathjustify.

     Moreover, the first optional argument of \tlabelrect (which gives
     the radius of the rounded corners) may now consist of the keyword
     "roundends" which tells mfpic to use the maximum reasonable radius:
     so that the short sides of the rectangle become half-circles.

  -- All commands that take an optional argument can now take an empty
     optional argument to select the default. Useful only when a command
     has 2 optional arguments and you want only to change the second.

  -- A command \overlaylabels (or package option) is available to make
     the behavior of labels under mplabels close to the same as without
     mplabels: this option causes them to be added last, on top of all
     picture elements. They are then not covered up by any drawing
     commands and they are not clipped off under the clip option or by
     the \gclip command.

  -- A command  \clearsymbols  (or package option) that makes
     \plotsymbol and \plotnodes behave like \point does when
     \pointfillfalse: the portions of the drawing in the interior of the
     open symbols is cleared (erased). \noclearsymbols restores the
     previous default.

  -- New figures:
     \makesector\arc
         Makes a sector by connecting the arc's center to the arc's
         endpoints. Calculates the center automatically.
     \mfbezier[<tens>]{<list>}
     \closedmfbezier[<tens>]{<list>}
         Connect the list of point with the standard MF connector ".."
         or optionally with "..tension <tens>..".
     \qbeziers{<list>}
     \closedqbeziers{<list>}
         Make a path by connecting the first point in the list to the
         third, then the fifth, etc., with quadratic Bezier curves using
         the second, fourth, etc., points as controls. The equivalent of
         a series of LaTeX \qbezier commands.
     \regpolygon{<n>}{<name>}{<eqn1>}{<eqn2>}
         Makes a regular polygon with n sides, <name> being a symbolic
         name for the array of points. The last two parameters are
         equations that should fix the location of two of the vertices,
         or of the center and one vertex. In the equations, <name>0 is
         the center, <name>1 through <name><n> are the vertices
         anticlockwise. Example:
             \regpolygon{17}{Bob}{Bob0=(0,0)}{Bob1=(0,1)}
         After this, the names Bob0 through Bob17 can be used in drawing
         commands where MF or MP point data is required (but not in TeX
         commands like \tlabel without mplabels).

  -- \pairarray{<name>}{<list-of-ordered-pairs>}
     \numericarray{<name>}{<list-of-numbers>}
     These define <name>1, <name>2, etc., as symbolic names for the
     elements in the list. After
        \pairarray{Bob}{(0,1),(1,2),(3,0)}
     one can draw a triangle with \polygon{Bob1,Bob2,Bob3}. The
     symbolic names are only recognized by MF or MP and so can't be
     used to position text without mplabels.

  -- \hgridlines{<yspace>}: like \gridlines, but draw only horizontal
     lines. Similarly:  \vgridlines{<xspace>} .  All three commands now
     draw their lines within the margins set by \axismargin and its
     relatives.

  -- \gridarcs{<dr>}: Like \plrgrid except only the arcs are drawn.
     Similarly: \gridrays{<dtheta>}

  -- Enhanced \barchart: the data can be ordered pairs that specifiy a
     _both_ ends of the bar (Gantt diagrams).

  -- Almost all commands that set or change an mfpic variable or value
     now arrange for the change to be global when outside an mfpic
     environment, unconstrained by other groups, but local when inside.
     The main exceptions are \store and \patharr, which need to be
     inside a picture to work at all and so are always global. There may
     be other exceptions.

  -- Some backward incompatibilities have been introduced; the above
     changes in scope is the main one. Also: a permitted but
     undocumented syntax in \plottext is no longer permitted. Points and
     symbols are drawn in pointcolor, where in the past the filled
     symbols were drawn in fillcolor and unfilled symbols in drawcolor.

  -- All old commands have been reexamined and most rewritten or
     tweaked. All known bugs have been removed. (Unknown bugs might well
     have been increased.)


This distribution, the latest updates, and some past versions, should also be
available at my web site:
<http://comp.uark.edu/~luecking/tex/mfpic.html>.

--
Dan Luecking  <luecking at uark dot edu>
Department of Mathematical Sciences
University of Arkansas
Fayetteville, Arkansas 72701-1201
U.S.A.