===============================================================
XFIG - Facility for Interactive Generation of figures under X11
===============================================================

Xfig is a menu-driven tool that allows the user to draw and manipulate objects
interactively in an X window.  The resulting pictures can be saved, printed
on postscript printers or converted to a variety of other formats (e.g. to
allow inclusion in LaTeX documents).

This file contains some notes about installing xfig, the directory
'Examples' contains some example figures and the 'Doc' directory contains
some further documentation including the manual in troff -man format
and PostScript.

Xfig and its postprocessor fig2dev (part of the TransFig package) are available
from ftp.x.org in /contrib/applications/drawing_tools and from any CTAN machine
(e.g. ftp.tex.ac.uk) in /pub/archive/graphics.
The site ftp.cdrom.com also has it in /pub/X11/contrib/applications/drawing_tools

***************************************************************************
Please send email about any questions/bug fixes/contributions etc. about
TransFig or xfig to xfig-bugs@epb1.lbl.gov.

Brian V. Smith
Lawrence Berkeley National Laboratory
xfig-bugs@epb1.lbl.gov
***************************************************************************

Note that although I work at Lawrence Berkeley National Laboratory (LBNL)
I don't speak for LBNL nor do I represent LBNL with respect to my work on
TransFig and xfig, nor does LBL make any representations about the suitability
of this software for any purpose.

Here is the legal part:

THE LAWRENCE BERKELEY NATIONAL LABORATORY DISCLAIMS ALL WARRANTIES WITH
REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS, IN NO EVENT SHALL THE AUTHORS 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.

And here is the copyright notice that you will find on every source file:

 FIG : Facility for Interactive Generation of figures
 Copyright (c) 1985-1988 by Supoj Sutanthavibul
 Parts Copyright (c) 1989-1998 by Brian V. Smith
 Parts Copyright (c) 1991 by Paul King
 
 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, distribute, sublicense,
 and/or sell 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.

______________________________________________________________________________

NOTE 1: Because Unisys has stated that they will not charge royalties for the
	use of the LZW compression algorithm in FREE programs, xfig will
	continue to support importing of GIF images (exporting is handled by
	the ppmtogif program in the netpbm[pbmplus] package).
	However, be aware that if you sell xfig, for example as part of
	a CD-ROM package with freeware, you may be liable for paying royalties
	to Unisys.
	It is recommended that you comment out the "#define USEGIF" line in the
	Imakefile before compiling and selling xfig.
	*** The authors of xfig and the Lawrence Berkeley Laboratory cannot be
	held responsible in any case. ***

NOTE 2: For exporting Fig files to any of the bitmap formats (e.g. GIF, JPEG)
	you will need to get a version of ghostscript that has jpeg, pcx256,
	pbmraw, ppmraw and tiff24nc drivers.  Ghostscript is available from
	ftp.cs.wisc.edu in /ghost/aladdin.
	fig2dev uses ghostscript for exporting and xfig uses it for importing
	PS and EPS files.

	Additionally, there is a bug in the pcx driver in Aladdin Ghostscript
	versions prior to 3.32, which writes an incorrect pcx file for images
	with odd width (not even).  There is a compile-time flag called PCXBUG
	in the Imakefile to make xfig add one pixel to the width of an
	odd-width image when it reads in the pcx output from Ghostscript.

===================
INSTALLATION NOTES:
===================

1. Edit the Imakefile if you need to customize it (see following notes).
	Specifically, if you want to install xfig in a directory other than
	the default X11 binary directory, add "BINDIR=<directory>" at the
	top of the Imakefile, where <directory> is the full path of the
	directory in which you want xfig to be installed.

2. Type "xmkmf" to create the Makefile from the Imakefile.  If you don't have
	xmkmf you can do "make Makefile".  In either case you must have imake,
	which can be found at the X Consortium site, ftp.x.org.

3. Type "make"         (**** This MUST be done before "make install" ****).
	Note: The "configure" script will be automatically run in the JPEG
	directory if you have commented out the USEINSTALLEDJPEG variable
	(i.e. you have defined the JPEGLIBDIR and other variables).
	This will create the Makefile in the JPEG directory from your system
	configuration.
	If for whatever reason, the configure script doesn't run, go into the
	JPEG directory and type "./configure" then "make".  Then go back to
	the xfig directory and continue with "make".

4. Type "make install"
	This will install the executable (xfig) into the execute directory,
	and the documentation files into xfig's library directory XFIGLIBDIR.
	There is a reference in HTML, a tutorial in PDF format, and the man 
	pages in PDF format, although the HTML files are much better than the
	man pages.  The Help menu in xfig will launch the browser to read the
	HTML files and the PDF viewer to view the other two.  The programs
	that are used for these are specified in the app-defaults file under
	Fig.browser and Fig.pdfviewer respectively.  The default for HTML is
	"netscape" and "acroread" for the PDF files.
	If your Netscape can read PDF files you may want to change the 
	Fig.pdfviewer resource to say "netscape" instead of "acroread".
	You can get both Netscape and Acroread for just about every platform.
	Netscape is available from Netscape Communications at:
		http://home.netscape.com
	and Acroread is available from Adobe at:
		http://www.adobe.com/prodindex/acrobat/readstep.html

   ****	If you don't do this step, be sure to install the app-defaults files
	Fig.ad and Fig-color.ad in the system app-defaults directory (usually
	/usr/lib/X11/app-defaults) as "Fig" and "Fig-color" respectively, and
	the CompKeyDB file in the directory specified by XFIGLIBDIR
	(default: /usr/local/lib/X11/xfig).
	There are two app-defaults files for colors: one I call the "classic"
	color scheme (blues for the buttons and primary colors for OK/CANCEL
	buttons) and a new one provided by Joel D. Young (jdyoung@afit.af.mil)
	which looks more like tcl, and I think is a little nicer.  It looks
	best when used with Xaw3d.1.0, which can show 3d relief for labels,
	not just buttons.  This new color set is the default.
	If you want the "classic" colors, copy Fig-color.classic.ad to your
	app-defaults directory as "Fig-color".

	If you can't install xfig in your system directories you may put it
	anywhere in your search path.  The app-defaults files (Fig.ad and
	Fig-color.ad) may be put into any directory as Fig and Fig-color
	respectively, and pointed to by setting the shell environment
	variable XAPPLRESDIR.  You may also put the CompKeyDB file in that
	directory and compile xfig with XFIGLIBDIR (in the Imakefile) pointing
	there.

5. Type "make install.man".

6. For X11R5 and later color X servers, specify "*customization: -color" in
	your .Xdefaults or .Xresources file.  This will make the system look
	in "Fig-color" for the resources, which then includes "Fig" for the
	non-color related resources.
	NOTE: this only works under X11R5 and later.


------------------------------
NOTES on changes to Imakefile:
------------------------------

o If you have a small screen (e.g. 800x600) you may want to uncomment
  the line with USESMALLICONS in the Imakefile to use smaller icons for the
  mode panel.

o For a 3D look, I recommend using Kaleb Keithley's 3D Athena Widget set, a
  direct replacement for the Xaw library.  After you compile and install that
  package, and after step 1 above, just uncomment the definition of XAWLIB in
  the Imakefile and it will use the 3D widget set.  This set is available from
  ftp.x.org in /contrib/widgets.

o If you *don't* want JPEG support, comment out the #define USEJPEG line in
  the Imakefile.

o If you *want* JPEG then:
  o If you already have a JPEG library in your system library directory leave
    the "#define USEINSTALLEDJPEG" line (don't comment it out) in the Imakefile.
  o If you don't have it installed, get it from one of the following places,
    comment out the #define USEINSTALLEDJPEG line in the Imakefile (using XCOMM)
    and point JPEGLIBDIR to the diredctory where the source is.  The default is
    ../jpeg (relative to the xfig source directory).
  o You must have version 5b or newer of the JPEG library.
  o The JPEG library is available from several places.  The official
    archive site is ftp.uu.net in /graphics/jpeg.
    Another is ftp.x.org in /contrib/libraries.
  o ** Make sure you delete or rename any older version of the JPEG
    library you might have on your system.  Some Linux systems come
    with an older version which is incompatible with xfig.

o If you want to use the XPM3 package (X11 color pixmaps) uncomment the
  #define USEXPM line (using XCOMM) in the Imakefile.
  With XPM support you can import xpm files as picture objects, and export
  figures as XPM files.
  Additionally, if you want to use the color icon for xfig (which is in
  XPM format) uncomment the #define USEXPM_ICON line in the Imakefile.
  You need xpm version 3.4c or newer.  This is available from ftp.x.org in
  /contrib/libraries. XPM usually comes with most Linux installations.

o If you have Ghostscript, xfig will attempt to use it to interpret any
  encapsulated Postscript (EPS) files you import.  Ghostscript must be compiled
  with with the "pcx256" and "pbmraw" drivers.  The pbm driver is used when you
  run xfig on a monochrome display and the pcx256 driver is used on a color
  display.
  See NOTE 2 above about the pcx driver in Ghostscript.

o If you don't have Ghostscript, remove the -DGSBIT flag in the "DEFINES" variable
  in the Imakefile.

o If you are using the HP compiler, add "-Aa -D_HPUX_SOURCE | -O" to the DEFINES
  variable in the Imakefile.  Note carefully the "|" which prevents the compiler
  from overriding the -O option.  Problems occur if the +O3 optimization is used.

o If your system doesn't have strstr(), uncomment the line with HAVE_NO_STRSTR
  in the Imakefile.

o If your system doesn't have strcasecmp() and/or strncasecmp(), uncomment the
  lines in the Imakefile with HAVE_NO_STRCASECMP and HAVE_NO_STRNCASECMP.

o If you have an input tablet and your X server supports the XInputExtension
  uncomment the lines that define TABLIB and USETAB in the Imakefile.
  Start xfig with -tablet or define the resource Fig.Tablet to use it.

o The maximum width of the top ruler is set to 1020 pixels and the height of the
  side ruler to 860 pixels.  If your server can handle pixmaps larger than this
  and you need longer/taller rulers, you may set the maximum allowed in your
  Imakefile with -DMAX_TOPRULER_WD=1160 (or whatever value you wish) and
  -DMAX_SIDERULER_HT=1024 (or whatever value you wish).

o The SMOOTHMOTION option toggles between two methods for tracking the
  cursor.  The first way (SMOOTHMOTION) just uses the (x,y) information given
  in the X pointer motion event.  If your display server doesn't implement
  motion compression this is very slow for large movements of the mouse
  pointer because X sends back lots of small movement events, each of which
  causes the rubberband box to be erased and redrawn.  The alternative
  way (not SMOOTHMOTION) queries the position of the X cursor whenever
  a motion event is received and if you make a large movement and then
  stop actually turns out to involve less work even though the XQueryPointer
  call is quite slow.
  The SMOOTHMOTION flag MIGHT be necessary for older versions of OpenWindows on
  certain machines if the performance is slow when moving or drawing objects.

o If you have a Sun Sparcstation and would like the Compose LED (light) turned
  on when you are entering multi-key characters (like a-umlaut, c-cedilla, etc), 
  uncomment the line: COMP_LED = -DCOMP_LED=3
  (Note: older versions of X11, e.g. R5 may use 1 instead of 3 for the LED)

o Look for any other comments in the Imakefile which describe options.

--------------
General NOTES:
--------------

The pattern shading (e.g. bricks, shingles, etc.) only work for PostScript,
and the bitmap output formats (e.g. GIF, JPEG, etc.).

Unless you have an image (picture object) in your figure, you may not gain
very much by exporting in JPEG over GIF because of the nature of compression
used in both methods.  GIF is usually better for line drawings or drawings
with large blocks of continuous color (e.g. filled polygons).  JPEG is usually
better for compressing (photograpic) images.

If you have the default paper size for Ghostscript as A4 (metric) change the
following (in gs_init.ps):

% Optionally choose a default paper size other than U.S. letter.
   (a4) /PAPERSIZE where { pop pop } { /PAPERSIZE exch def } ifelse

to
   systemdict /DEVICEWIDTH known systemdict /DEVICEHEIGHT known or not
    { (a4) /PAPERSIZE where { pop pop } { /PAPERSIZE exch def } ifelse
    } if

----------------------
Printing your figures:
----------------------

The program to translate your figure into one of many printer languages
(Postscript, LaTex, etc) is called fig2dev and is part of the TransFig
package put together by Micah Beck and maintained by me, Brian Smith.
It is available from ftp.x.org in /contrib/applications/drawing_tools/transfig.
See the man pages for more information.

If you have a SYSV system but use BSD-style printing (lpr instead of lp) you
must define -DBSDLPR in the Imakefile/Makefile.

You may also need to uncomment the following string in the Fig.ad
app-defaults file:

!Fig*job_params*string:		-T PS

--------------
Solaris users:
--------------

You should have:

#define SystemV4 YES

in your imake machine config file (usually in /usr/lib/X11/config/<machine>.cf
or something like that).

Some people have had trouble with the Sun cc 3.0.1 compiler and optimization.
You may need to shut off optimization.
A common symptom is that xfig just core dumps when starting.

--------------
XFree86 Users:
--------------

Version 3.1 of XFree86 causes problems.  Get version 3.1.1 or newer.

------------------------------------------------------
Possible problems encountered installing/running xfig:
------------------------------------------------------

PROBLEM:
	icons in side and bottom panels appear then disappear

POSSIBLE CAUSE AND SOLUTION:
	On Linux (2.0.29 at least), the libNextaw version of the Athena Widget
	set (libXaw) seem to cause this problem.
	Relink with vanilla libXaw or libXaw3d.
________________________________________________________________________________
PROBLEM:
	A warning about some action not found occurs, e.g.:
	Warning: Actions not found: ModeOpenCompound

POSSIBLE CAUSE AND SOLUTION:
	You didn't install the app-defaults files.
________________________________________________________________________________
PROBLEM:
	X error occurs with X_SetClipRectangles as the Request code

	or:

	Thick line shows through arrowhead in certain orientations.

POSSIBLE CAUSE AND SOLUTION:
	In X11R5 there was a bug in the clipping algorithm (Xlib).  Switch to
	X11R6 or apply the following patch to mit/lib/X/XPolyReg.c in the
	X11R5 library:

*** XPolyReg.c.orig	Tue Dec 15 12:01:22 1992
--- XPolyReg.c	Wed Nov 15 09:41:13 1995
***************
*** 402,408 ****
  	    if (numRects && pts->x == rects->x1 && pts->y == rects->y2 &&
  		pts[1].x == rects->x2 &&
  		(numRects == 1 || rects[-1].y1 != rects->y1) &&
! 		(!i || pts[2].y > pts[1].y)) {
  		rects->y2 = pts[1].y + 1;
  		continue;
  	    }
--- 402,409 ----
  	    if (numRects && pts->x == rects->x1 && pts->y == rects->y2 &&
  		pts[1].x == rects->x2 &&
  		(numRects == 1 || rects[-1].y1 != rects->y1) &&
! 		/* Fixed version from X11 R6 */
! 		(i && pts[2].y > pts[1].y)) {
  		rects->y2 = pts[1].y + 1;
  		continue;
  	    }
________________________________________________________________________________
PROBLEM:
	When using LaTeX fonts in Xfig I always end up with postscript
	fonts instead rather than, say, Computer Modern.

POSSIBLE CAUSE AND SOLUTION:
	To put fonts under the control of LaTeX when generating PS, you must
	tag the text object as "special" and then use the pstex output mode.
	This mode forces special text objects to be passed through to LaTeX,
	allowing the use of Math mode and CM fonts among other things.
________________________________________________________________________________
PROBLEM:
	On a DEC Alpha the compiler may complain about something like: ".mask
	must have pcreg from .frame set if any bits are set in .mask or .fmask"
	in the file u_bound.c.

POSSIBLE CAUSE AND SOLUTION:
	Set the optimization level to -O1 at least for that file.
________________________________________________________________________________
PROBLEM:
	On Sun machines the linker may give erroneous error messages about
	the following symbols being undefined:

	ld: Undefined symbol
	   _get_applicationShellWidgetClass
	   _get_wmShellWidgetClass

	This may be ignored as it is a problem with the Sun shared libraries
	and the way X11 builds the shared Xmu library.  It doesn't affect the
	operation of xfig.

	Or you may compile with "-Bstatic -lXmu -Bdynamic".
	To really solve the problem if you are using OpenWindows 3.0
	(X11R4-based Xt), please contact your local Sun office and request the
	following patches:

        Patch i.d.      Description
        100512-02       4.1.x OpenWindows 3.0 libXt Jumbo patch
        100573-03       4.1.x OpenWindows 3.0 undefined symbols when using
                                shared libXmu

	A source patch for use with the MIT X11R4 libraries was developed by
	Conrad Kimball (cek@sdc.boeing.com); it retrofits into R4 some fixes
	made in R5 to get around this problem. The patch is on export in [1/93]
	contrib/X11R4_sunos4.1.2_patch_version3.Z".

	The other option is to use X11R5 or X11R6.
________________________________________________________________________________
PROBLEM:
	The window oscillates and fights with the window manager when
	I click on a mode button or try to resize the xfig window.

POSSIBLE CAUSE AND SOLUTION:
 	Perhaps the following resource has been set
 		*allowShellResize: true
	because another program requires it to be true.
	Change the resource to be specific to the programs which need it,
	or set the following resource:
 		Fig*allowShellResize: false
	Note: this is in the Fig.ad file that comes with xfig, which is
	      installed when you do a "make install".
________________________________________________________________________________
PROBLEM:
	Openwindows sometimes loses track of xfig's icon.

POSSIBLE CAUSE AND SOLUTION:
	Cause unknown, here is a temporary kludge. Place the line:
		Fig*iconPixmap:               ..../your_lib_area/fig.icon.X
	in your .Xdefaults file and copy fig.icon.X into your lib area.
________________________________________________________________________________
PROBLEM:
	When compiling on an HP 750 running HP-UX 8.05, the compiler dies with
	a bus error in the file u_undo.c.

POSSIBLE CAUSE AND SOLUTION:
	There is a bug in the HP compiler.  Workaround the problem by adding
	an extra statement between two statements in u_undo.c:

	Original:

	undo_glue()
	{
	    list_delete_compound(&objects.compounds, saved_objects.compounds);
	    tail(&objects, &object_tails);

	New:

	undo_glue()
	{
	    list_delete_compound(&objects.compounds, saved_objects.compounds);
>>>	    /* HP-UX 8.05 compiler bug fix -- don't ask */
>>>	    last_action = last_action;
	    tail(&objects, &object_tails);
________________________________________________________________________________
PROBLEM:
	On HP machines, the capitalization of some letters in the text window
	in the edit popup for text objects are wrong.

POSSIBLE CAUSE AND SOLUTION:
	Make sure that the CompKeyDB file has the lowercase letter definitions
	BEFORE the uppercase definitions.  This should be the case for the
	CompKeyDB file shipped with xfig 2.1.5 and later.
________________________________________________________________________________
PROBLEM:
	On some HP computers using native cc compiler there is a problem with
	level 3 optimization.

POSSIBLE CAUSE AND SOLUTION:
	Use +O2 instead of +O3 or get patch from HP for the compiler from
	http://support.mayfield.hp.com/
	Choose: Patch Browsing and Downloading
________________________________________________________________________________
PROBLEM:
	On Linux, you may get errors such as:
	   > f_wrjpg.o(.text+0x5b2): undefined reference to `jpeg_write_scanlines'
	   > f_wrjpg.o(.text+0x5dc): undefined reference to `jpeg_finish_compress'
	   > f_wrjpg.o(.text+0x5e2): undefined reference to `jpeg_destroy_compress'

POSSIBLE CAUSE AND SOLUTION:
	On most Linux machines, there is an old version of the JPEG library
	already installed, and is incompatible with xfig.
	Delete its library files (usually /usr/local/lib/libjpeg.so and
	/usr/local/lib/libjpeg.a) and the header file (usually
	/usr/local/include/jpegdata.h)
________________________________________________________________________________
PROBLEM:
	Arc-boxes don't appear correct when viewing exported PostScript with
	ghostview or ghostscript.

POSSIBLE CAUSE AND SOLUTION:
	Ghostscript version 4.01 has a bug with the arcto operators.
	Get version 4.03 or newer.


----------------
Artwork credits:
----------------

This section gives credit to those people who have contributed to the Examples
directory.
Any figures not listed here were probably done by Brian Smith.

Fig file	Description			Artist
--------	-----------			------
antennas.fig	various ultra-wideband antennas	(can't remember who submitted this)

sowpig.fig	RAAF F-111C fighter		Carlo Kopp (he has an "Unofficial F-111"
		w/2xAGM-142 Have Nap SOWs	web page at:
rfxc.fig	RFX Strike/Recon Fighter	http://www.cs.monash.edu.au/~carlo/archive/MILITARY/F-111/
greenpig.fig	F/RF-111C/G Tactical Fighter
lidar.fig	Sidelooking battlefield surveillance LIDAR

linuxlogo.fig	This was an entry in the	Philipp Reisner
		Linux 2.0 Logo contest

clp_computer.fig computer clipart		W. Chimiak (chim@tachyon.medeng.wfu.edu)
clp_network.fig	 computer network clipart
clp_bldgs.fig	 various buildings clipart

illusion.fig	"impossible" 3-D object		Vivek Khera (khera@cs.duke.edu)
recycle.fig	recycling logo

flowchart.fig	flowchart building blocks	Tim P. Starrin (noid@cyborg.larc.nasa.gov)

logo.fig	first fig file using imported	Bryan Boyter (original author of eps
		eps object			import code for xfig)
transit.fig	transit map of Saint John,	Robort Ford (rford@mailserv.mta.ca)
		New Brunswick (Canada)
		** Don't use it for locating transit routes. It is only good
		through July 1996 and only shows non-rush-hour routes **
aircraft.fig	light aircraft			Peter Hiscocks (phiscock@ee.ryerson.ca)
ps-foil.fig	power supply circuit board foil layout
ps-schematic.fig  power supply circuit board schematic
clp_computer.fig various computers, monitors etc.  W. Chimiak (chim@tachyon.medeng.wfu.edu)
clp_network.fig	computer network components