SHORT VERSION
-------------

To install StarPlot, you will need:

* the GTK+ and GDK libraries, version 1.2, including the gtk-config utility.
  Check for the presence of gtk.h, gdk.h and gtk-config on your system.

* a recent C++ compiler, preferably g++ version 2.95.x or newer

That's it!  Just type "make" (or "gmake", whichever will get you GNU make),
then as root, "make install".

You can also make a StarPlot Debian package - see note 4) below.

ADDITIONAL NOTES
----------------

1) Installation details

The default StarPlot install will install the following files to your system:

/usr/local/bin/starplot                 The graphical star chart viewer
/usr/local/bin/starconvert		Utility program for datafile conversion
/usr/local/share/starplot/test.stars    A test data file [*]
/usr/local/share/starplot/sample.stars  Example; read this for file format info
/usr/local/share/doc/starplot/		Directory containing HTML documentation
/usr/local/share/man/man1/starplot.1	Brief man pages (mostly just
/usr/local/share/man/man1/starconvert.1  pointers to HTML documentation)

[*] Do not cat test.stars to your terminal - it is for testing the ability of
the StarPlot parser to handle garbage input gracefully, so it contains binary
junk.

If you need any of the above files to be installed somewhere else (e.g. if you 
don't have root access), or if you want them to be named something else, just
edit the first several variable definitions in the Makefile in this directory.

2) Extended ASCII characters in GTK

In version 0.92 and above of StarPlot, I have used the letter "d" to
stand for degrees of arc.  This is because some recent versions of the GTK+
library will not display extended ASCII characters (like the degree symbol,
ASCII 0xB0) with the LANG environment variable set to the default of "C".  If
you want the characters, add the flag -DEXTENDED_ASCII to the CFLAGS variable
in the Makefile and set your LANG variable to "en_US" (or something like that)
to obtain the original behavior.

Unfortunately, data files which were installed using an earlier version of
starconvert will still contain the extended ASCII degree symbol.  You may want
to use "tr" or "sed" or other utility to change all the degree symbols in
those data files into spaces.

3) Compiler and system issues

StarPlot is currently known to compile with g++ versions 2.95.x and 3.0.x;
also with egcs 1.1.2 (corresponding to g++ version 2.91.66) and version 5.0.1
of Intel's C++ compiler for Linux.  I highly recommend using g++ 2.95.x if
you have it.

Should you be using a compiler other than g++, you will need to specify your
compiler name in the Makefile's CXX variable and perhaps edit the CFLAGS
variable.  Also, your compiler may not support the snprintf, strcasecmp or
strncasecmp functions.  (They aren't in the ANSI C/C++ standard.)
If not, add the flags -DNO_SNPRINTF and/or -DNO_STRCASECMP to the CFLAGS 
variable in the Makefile.  You should not need to edit any Makefiles except the
top-level one in this directory.

Platform-specific notes (this will be added to as I receive reports):
* Should compile with no modifications on recent Linux (tested on RedHat 6.2,
  CorelLinux 1.0 and Debian woody / sid).
* Older versions of libc have no snprintf() function.  If you are using
  a gcc/egcs version from before 2.95.x, the compilation assumes you don't
  have snprintf().  This assumption may be wrong, in which case you will
  probably get compiler warnings about it.  To override it, use
  -DWITH_SNPRINTF.

If you successfully compile StarPlot on a platform other than Linux x86,
drop me a note at <kmccarty@princeton.edu> with your platform information
and any special workarounds it required.  Someday I'll get around to
making an autoconf script to set these things automatically.

4) Debian packaging

Thanks to Javier Fernandez-Sanguino Pen~a, you can now install StarPlot
directly from the testing or unstable distributions of the official Debian
archive: "apt-get install starplot".

Debian's version may be a couple versions behind the latest StarPlot release
available on the website.  You can create a StarPlot Debian package from this
source code by issuing the command "debian/rules binary" from the
starplot-<version> directory.  (You must be root, or use fakeroot or some such
program, to do this.)  The package will be built in the parent directory.  Then
you may run "make debian-clean" to clean up the source tree.

To install the package, run "dpkg -i ../starplot_<version>_<system>.deb" as
root.  Of course, installing the .deb will put all the StarPlot files into
the /usr hierarchy instead of /usr/local.  To clean up the source tree after
making a Debian package, "make debian-clean".

