The XFIGFRAG tool, v. 1.0
              Eric Colin de Verdiere, 2005.12.29
             Eric.Colin.de.Verdiere --a/t-- ens.fr

INTRODUCTION

Xfigfrag is a tool for inserting arbitrary LaTeX code in figures created by
xfig.  It is used in a similar way as the psfrag package but, unlike the
latter, xfigfrag also works with pdflatex; it can thus be used as a
`pdffrag' package.  As a drawback, xfigfrag only works with figures created
by xfig.

This tool can be useful but is still in development and also has some
limitations (see `Technical Precisions' below); however, many of these
limitations could be overcome.  If you are interested in this tool and you
would like some features to be implemented, please send me feedback!

PRESENTATION

There are several methods for inserting LaTeX code in figures.  Natural
requirements for this are:
 * that the figures can be scaled easily, e.g. to have the same width as
   the current page;
 * that the scaling does not affect the size of the text (which must be of
   the same size as the text of the whole LaTeX document, regardless of the
   magnification of the figure).
The second requirement is not met when using special text in xfig figures,
exporting the figure in .pstex and .pstex_t formats, or using MetaPost.
It is still possible to export xfig figures directly into LaTeX format, but
there are severe restrictions in terms of drawing capabilities.  Finally,
the psfrag package is adequate with respect to the two criteria above, but
it inherently uses the structure of the eps files, so it only works with
latex, not pdflatex.

The xfigfrag tool is designed to overcome these difficulties.  The user
draws the figure using xfig, exports it into two special formats using (a
patched version of) fig2dev, includes the figure in the LaTeX document
using the graphicx package (\includegraphics command) and inserts text in
the figure using the same syntax as the psfrag package.

INSTALLATION

To install xfigfrag:

 * Download transfig.3.2.4.tar.gz (the sources of transfig, a part of the
   xfig program); it contains in particular the sources of fig2dev, the
   program used to export fig files to many image formats.
 * Copy the xfigfrag files as follows:
   - cp drivers.h transfig.3.2.4/fig2dev/drivers.h
   - cp Imakefile transfig.3.2.4/fig2dev/dev/
   - cp genfrg.c transfig.3.2.4/fig2dev/dev/
 * Build this patched version of fig2dev.  When compiling (using gcc 3.4.4)
   I had to make small changes:
   - cp fig2dev.h transfig.3.2.4/fig2dev/
   - cp gensvg.c transfig.3.2.4/fig2dev/dev/
 * Copy xfigfrag.sty in a directory searched by LaTeX.
 * The xfigfrag tool needs the graphicx package, distributed in any LaTeX
   distribution.  This software has been tested with the following version
   of graphicx: 1999/02/16 v1.0f  Enhanced LaTeX Graphics (DPC,SPQR).
 * (Optional) To compile the example:
   - fig2dev -Lfrg fig.fig fig.frg
   - fig2dev -Lpdffrg -p dummy fig.fig fig.pdf
   - fig2dev -Lepsfrg fig.fig fig.eps
   - (pdf)latex test

USE OF XFIGFRAG

 * Create your figure using xfig.  Where some text will have to be
   inserted in the document, insert some mnemonic tag of text instead
   (no need to use the `special text' flag of xfig).
 * Export the figure in two formats:
   - epsfrg or pdffrg, depending on whether you use latex or pdflatex:
           fig2dev -Lepsfrg foo.fig foo.eps
           fig2dev -Lpdffrg -p dummy foo.fig foo.pdf
     (the -p dummy argument seems to be necessary to preserve the
     orientation of the figure).  The created file contains the figure
     without text;
   - frg:  fig2dev -Lfrg foo.fig foo.frg
     The created file contains the information for text placement.
 * Put the figure (eps or pdf, and frg) in a directory searched by LaTeX
   (see the \graphicspath command).
 * Use \usepackage[psfrag]{xfigfrag} instead of \usepackage{psfrag} in your
   LaTeX document.
 * Use the usual command \psfrag of the psfrag package and the graphicx
   package with \includegraphics.  The filename given to \includegraphics
   should have no extension (anyway, graphicx finds the appopriate
   extension automatically).

TECHNICAL PRECISIONS

Here are some more subtle precisions on xfigfrag, compared to psfrag.  The
items marked with a ? could probably be resolved (send me e-mail):
 * If some text in the .fig file has no associated \psfrag command, it will
   be displayed, but not with the attributes (font, size, angle,
   color, ...) it was created in xfig.
 * xfigfrag only works in conjunction with the graphicx package (not
   graphics).
 * If, in the .fig file, some text that is hidden by some other object of
   smaller depth, the text (\psfragged or not) will actually not be hidden.
 ? The mandatory argument of \includegraphics should be a filename without
   extension.
 ? The syntax \includegraphics[llx,lly][urx,ury]{foo} is not supported.
 ? When using \includegraphics*, the text is not clipped.
 ? The \psfrag commands accepts only the syntax \psfrag{tag}{value},
   without any optional arguments.
 ? The tags in the \psfrag commands must consist of one single word of
   text, without special characters.
 ? The xfigfrag package reproduces (some of) the bugs (or non-implemented
   features) of psfrag.  In particular, when a combination of rotation and
   scaling is used in \includegraphics, the text is not displayed
   correctly.
 ? Currently, the only possible file types for exporting figures are .eps
   and .pdf.
 ? Rotation of the text could be avoided when rotating the figure.

LEGAL BLURB

Any party obtaining a copy of these files is granted, free of charge, a
full and unrestricted irrevocable, world-wide, paid up, royalty-free,
nonexclusive right and license to deal in this software and documentation
files (the ``Software''), including without limitation the rights to use,
copy, modify, merge, publish and/or distribute copies of the Software, and
to permit persons who receive copies from any such party to do so, with the
only requirement being that this copyright notice remain intact.

The author disclaims all warranties with regard to this software, including
all implied warranties of merchantability and fitness; in no event shall
the author be liable for any special, indirect, or consequential damages or
any damages whatsoever resulting from loss of use, data, or profits,
whether in an action of contract, negligence, or other tortious action,
arising out of or in connection with the use or performance of this
software.