% jfig/doc/export-fig2dev.txt (26.10.2002)


Exporting and printing jfig files:


Perhaps the most common usage of xfig/jfig is to produce drawings
for LaTeX (or Word etc) documents. This requires to convert the FIG
format into a file format understood by the word processor.

Contents:

1) native printing and Postscript export
2) PPM export
3) fig2dev
4) fig2dev on the server
5) fig2dev problems


------------------------------------------------------------------------


1) Native printing and Postscript export

The easiest way to export your FIG file into another format is to use
the Java printing functions. Select "Menu->File->Print (java native)"
and select the options offered by the print dialog. To convert your
drawings to Postscript format, just select a Postscript printer and
select "print to file":

o On Unix systems, printing will always generate Postscript output, 
  and you should be able to select paper format and orientation. 

o On Windows, you have full access to the Windows printing system.

  Note that you can always install a Postscript printer driver, even 
  if no Postscript printer is actually attached to your system.

  However, some Windows printer drivers generate quite un-portable 
  Postscript code. If in doubt, use the generic Postscript driver from
  Adobe. Another choice is to use the Apple Laserwriter II NTX driver,
  which is limited to 300dpi black and white but generates good output.

With a Java 1.1 virtual machine, jfig always uses the current coordinate 
transformation for printing.  You may have to experiment a little, 
in order to find acceptable zoom and translation settings.

The print quality depends on your Java virtual machine and the printer
driver. In general, Java 1.1 gives poor quality results: font rendering
is ok, but lines are limited to the resolution of 72dpi. This might 
result in "jaggy" lines for arcs and splines.

In theory, Java 1.2 should generate very high quality output, as jfig
calls Java2D functions for printing. However, Java2D printing is very
buggy at the moment (to put it mildly). Depending on your Java version,
results range from JVM core dumps to endless loops to missing objects
to excellent. 

Don't hesitate to report Java2D printing bugs to Sun Microsystems.


------------------------------------------------------------------------


2) PPM image export

The second export option is to use the "Menu->Export->PPM..." command.
This will prompt you for a filename and write a copy of the current 
screen display without grid and cursor in PPM portable pixmap format
(PPM raw format). Internally, this just renders the offscreen-buffer 
into a file - it is essentially a screenshot.

This may take a few seconds but should work with any JVM, the display
quality depending on the current window size and display settings like
anti-aliasing. However, there is currently no way to generate output
with higher resolution than offered by your monitor.

Note that typical image file sizes are 100KB .. a few MB, because PPM
is an uncompressed image format. To save disk space, use your favorite
image viewer (PaintShopPro, Microsoft Photo Editor, GIMP, xv, ...)
to convert PPM files into other file formats.

If the required class libraries are found on your system, jfig will
also enable menu items for additional output formats. For GIF export, 
jfig relies on the GIFEncoder package, whose classes are not included 
with jfig for copyright reasons. 


------------------------------------------------------------------------


3) fig2dev

Like xfig, jfig writes and reads FIG files, but offers no import
or export filters to other file formats. However, it is possible
to use the xfig companion program "fig2dev" to convert FIG files
into many other output formats, including Postscript, HPGL, or
LaTeX drawing commands.

Unfortunately, there is no Java implementation of fig2dev available.
Instead, you have to compile the fig2dev program for yourself, or
download a precompiled binary from our server. Most Linux and Unix
systems have fig2dev preinstalled together with the X11 programs.

For Windows, you can download the fig2dev-windows.zip archive
from our webpage, which includes a fig2dev.3.2.3 executable for
Windows 95/98/NT/2000. See the README in the fig2dev-windows.zip
archive for details and copyright information. 
After installing the fig2dev.exe and cygwin.dll, you should try to 
run the program "by hand" directly from the command line. Open a DOS 
shell and try 
fig2dev -help
fig2dev -L ps somefile.fig > somefile.ps
This should generate the Postscript version of your input file.
At the moment, the Windows fig2dev only supports JPEG format for 
embedded images.

---

Note: It is probably a good idea to write a small script (or makefile)
to run fig2dev with the required options and for all files in question,
instead of calling fig2dev directly.  This way, you won't forget to 
export the one drawing you edited two days ago... Also, you are saved 
the trouble to get the interaction between jfig and fig2dev working.

---

To access the external fig2dev program, jfig generates a String with
the command line and calls the systeme (e.g. DOS/Windows) to execute 
the command.  You can specify parts of the command via settings in your 
.jfigrc (jfig.cnf) file(s). Again, the whole process is currently limited 
by a number of severe Java VM bugs.

The approach taken by jfig is:

o) use temporary file names, in order not to destroy the original files.
o) call fig2dev 
o) don't wait for fig2dev to finish, because this deadlocks easily on
   many systems
o) because we don't know that fig2dev is finished, we cannot remove the
   tmp files. You will have to do this by hand from time to time.

---

Volunteers: The whole process is error prone and depends on your 
installation (what JVM, what fig2dev, ...). The export code in jfig 
was written two years ago and has never been improved or fixed, because
the script/makefile approach is better. However, many people like to
export each figure by selecting all the export options individually.
Please consider to contribute a fixed Java version of the corresponding
classes (jfig.gui.ExportOptionsDialog and jfig.gui.Exporter).
The source code for these classes is included with the latest jfig
class archive.


------------------------------------------------------------------------


4) fig2dev on the server

Given the current state of affairs with running fig2dev on Windows,
you might be tempted to run fig2dev on a Linux or Unix box near you.
This is in fact what the author of these lines does:
I use jfig on my Linux and Windows systems - the latter with a 
three-button mouse driver - but I don't run fig2dev on Windows at all. 
We have a Samba server running, and all the FIG files are on the server.
To export, I simply log onto the server and start my export script.

The jfig.jar archive contains a simple example script to convert all 
.fig files in the current directory to Postscript at 90% magnification 
in file /jfig/doc/run-fig2dev:

#!/bin/csh -f
foreach i (*.fig)
echo $i
./fig2dev -L ps -P -m 0.9 $i `basename $i .fig`.ps
end


------------------------------------------------------------------------


5) fig2dev problems

The algorithm used by fig2dev for splines is different from the
algorithm used in xfig 3.2, which is different from the algorithm
used in xfig 3.1. Jfig uses either the 3.2 or the 3.1 algorithm...

Therefore, "interpolated" splines may look quite different on paper 
after exporting and printing than they looked in xfig on the screen. 
This is most notable for splines which have "sharp" curves. If this 
is a problem, use "standard" (instead of "interpolated") splines...

