The XFIGFRAG tool, v. 1.1
              Eric Colin de Verdiere, 2006.06.06
             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) on www.xfig.org; 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).

ADVANCED FEATURE

By default, all texts of the .fig file are put in the .frg file.  Text not
\psfrag'ed may be not rendered perfectly, because PostScript fonts are not
available and for many other reasons.  So it might be desirable to
selectively put some texts in the .frg file and the other ones in the
picture.  The -i option of fig2dev (for languages frg, epsfrg, and pdffrg)
allows this.  It is followed by a numerical argument:
 * 0 (default): all texts are put in the .frg file;
 * 1: text with special attribute is put in the picture file;
 * 2: text without special attribute is put in the picture file;
 * 3: text with PostScript font is put in the picture file.
Unless you want to obtain strange results, you should use the same
parameter for the -i option when creating the .frg file and the picture
(.eps or .pdf).

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):
 * 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.
 * Special characters like {}\ in text are forbidden.
 ? There may be some differences compared with psfrag, in the case of text
   that has no associated \psfrag command.  The most notable difference
   occurs when PostScript fonts are used.
 ? 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 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.
 ? Possible extensions may include avoiding to rotate the text when
   rotating the figure using the \includegraphics[rotate=...] command.

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.