		      xsky 2.0 - a computerized star atlas



First, let's take a look  at what we have.  You're  reading this, so  you've
successfully obtained the xsky distribution and unpacked the tar file into a
directory.   xsky  consists  of  a number of required C files  and a  larger
number of optional C files; the optional ones are files required to read and
handle the various supported catalogs.

Which catalogs are available is specified by definitions in catdefs.h.  As
shipped, catdefs.h specifies inclusion of just the three catalogs distributed
with xsky.  Edit catdefs.h to move the appropriate "#define HAVE_xxx" lines
into or out of the "#if 0 ... #endif" as necessary.  For instance, if the
CD-ROM catalogs are available, move those "#define" lines.

You're now ready to build xsky.   There are two ways  to do this: a Makefile
called Makefile.std is  provided; you'll need to edit  the  INCLUDES line to
point to  your  Athena widget and X  Toolkit header file directory, and edit
the BINDIR line to point to the directory into which you wish to install the
executable.   LIBDIR  is defined as the directory into which  the library of
catalog routines should be installed; customize that as well.

Using Makefile.std will  compile  all  the C files, create a  library called
"libsky.a" containing the catalog-specific object  files, and link xsky with
your choice of catalogs,  as given by catdefs.h.  Save the .o files and this
library;  if you obtain  additional  catalogs  at a  later time, it is  only
necessary  to edit catdefs.h  and  do  another make; only catalog.c will  be
recompiled, and the correct set of catalog routines will  be loaded from the
library.

Alternatively, an Imakefile is provided.  Running "xmkmf" followed  by "make
depend" will create a Makefile that should build xsky correctly.  Note  that
the install  command  in the  Makefile  will install xsky  in the  directory
specified  by  BINDIR;  if  you  wish  to  install it  somewhere else,  edit
Imakefile  to  redefine  BINDIR.   The Imakefile  doesn't  create  a catalog
library; you'll need to hang onto all the .o files.

xsky is known to compile  cleanly  and  run under Ultrix cc;  while it  will
probably also  build successfully  under c89, for some reason  that compiler
wants to allocate space in the .o file for  the huge uninitialized arrays in
the SAO  catalog  routines.   This  results  in  .o  files  in  excess of  8
megabytes,  so I've  blown off  using this  compiler  until  the problem  is
resolved.

xsky is also known to build successfully unnder SunOs cc and gcc.  Others on
the net have successfully compiled and run  previous  versions  of xsky with
little or no trouble on Silicon Graphics, Hewlett-Packard, Data General, and
IBM  workstations.  Nothing  new has been introduced which should invalidate
those  results.  If you get  lots of  errors, and fundamental things such as
XtPointer appear to  be  undefined, you've gotten hold  of  a set  of  badly
broken header files that seem to appear  in both SunOS and Ultrix.  Grep the
file  Intrinsic.h for  "XtPointer";  if it's not  found,  you'll  need to go
hunting for a better set of header files.

Once xsky is compiled and  loaded successfully, "make install" will copy the
executable to the directory specified by BINDIR.

There are  two  C  shell scripts provided:  makebin will  create zero-length
files which  will  hold the dumps of the in-core  databases xsky creates for
each  file.  Allowing xsky  to use these binary  files  greatly improves the
startup  time.  xskyenv will set  environment variables which  point to  the
paths containing the binary database files and  the raw catalog files.  This
file should  be edited to define  these environment variables correctly, and
then executed before running xsky.

When xsky  executes, it looks for the binary database file for each catalog;
If xsky finds the file, it reads the file in as its internal binary database
for the catalog.  If the file is  found, but is  empty, xsky reads the ASCII
catalog file,  builds the  in-core  database,  and  writes  it to  the  file
(assuming write permission is  available).  If  the file is  not found, xsky
takes that as an indication that it is  not to dump the in-core database for
that catalog.

It  is suggested that a  standard location be created for the xsky  catalogs
and binary  databases.  The binary  databases need be built  just once; they
can be shared by  all users running the same  xsky  executable.   Subsequent
invocations  of xsky will read the binary databases instead of building them
from the raw catalog data.  This greatly speeds up xsky startup.

This is especially desirable as some of the binary databases are large; here
are the  sizes  of the  binary  databases as built by the cc  compiler under
Ultrix 4.3:

    291080 bsc5.bin
   2355528 dbl.bin
    909928 gcvs.bin
     37184 qso.bin
    195920 rngc.bin
   8286792 sao.bin
   8286216 saoj2000.bin
    724456 var.bin
   2355528 wds.bin
    291080 ybs.bin

A resource file called XSky is provided; this should be placed in a standard
location where it  can be accessed  by  all users of xsky.  It  is important
that X know where  to  find this resource file at run time; without it,  the
menu buttons will not be  properly labelled, and  many features of xsky will
not function.  The simplest way for X to locate this resource file is to set
the environment variable XAPPLRESDIR to the path containing XSky.

The font resources  are likely to be the source of a fair amount of trouble;
the XSky resource file specifies the fonts needed as follows:

*displaylatinfont:  *-helvetica-*-*-*-*-10-*
*displaygreekfont:  -adobe-symbol-medium-r-normal--12-*

If those font names don't work for you, comment out those two lines in XSky,
and uncomment  the lines  which read  simply "helvetica10"  and  "symbol12".
Then  create font alias by those names  and point them to fonts you do  have
available.  Recall that the symbol  font  is a Greek-letter font; it is used
by xsky to label stars with Bayer designations.


Quick installation:

If you have no catalogs other than the  ones distributed with xsky,  and are
building xsky  for personal use, not system-wide installation,  these  steps
will get up and running quickly.  Do this under the C shell.

1)  unpack the kit and read this file; you should also read blurb and README

2)  make -f Makefile.std depend
    make -f Makefile.std

	or

    xmkmf
    make depend
    make

3)  source xskyenv

4)  execute the makebin script; this will create empty binary database files
	for each possible catalog

5)  setenv XAPPLRESDIR .

6)  xsky &


Full installation:

Step-by-step  instructions  for  system-wide  installation  (see  above  for
clarification); do this under the C shell:

1)  unpack the kit and read this file; you should also read blurb and README

2)  edit catdefs.h to include the catalogs you'll have available at your site

3)  uncomment the lines in xskyenv and makebin corresponding to the catalogs
	you have

4)  make -f Makefile.std depend
    make -f Makefile.std

	or

    xmkmf
    make depend
    make

5)  edit xskyenv to define the environment variables which point to the
	catalog directories; leave the xxx_BIN variables pointed to "."
	for the time being.  if you haven't moved ybs.dat, rngc.dat, and
	qso.dat, leave their xxx_PATH variables pointed to "." as well

6)  source xskyenv

7)  execute the makebin script; this will create empty binary database files
	for each possible catalog

8)  setenv XAPPLRESDIR .
	this step is only necessary if you're going to run xsky without
	the -bin option

9)  xsky -bin
	this will:

	a)  read the text databases and build the in-core databases
		(this will take quite some time, if you're processing
		 some of the larger databases, like the SAO catalogs.
		 don't panic for at least ten minutes)
	b)  write the in-core databases into the *.bin files
	c)  exit without contacting the X Window System (thus the full
		xsky installation can be done from an ordinary terminal)

10)  remove any still-empty *.bin files; you won't need those unless you
	change catdefs.h to add new catalogs

11)  you now have:
	a)  an xsky executable
	b)  some text database files (*.dat)
	b)  some binary database files (*.bin)
	c)  some *.o files
	d)  libsky.a (if you used Makefile.std)
	e)  the XSky resource file

12)  save the *.o (and libsky.a) file somewhere if you'd like to save
	yourself the compilation time should you ever need to rebuild xsky;
	otherwise, they're superfluous at this point.  note, however, that
	if you add a new catalog, the only recompilation necessary is of
	catalog.c, so the object files and library might be worth saving.
	While you're at it, you might want to save the Makefile.std or
	Makefile (whichever you used) with all the dependencies built in.

13)  place the executable in a publicly-accessible area (like
	/usr/local/bin/X11/)

14)  place the text database files in a publicly-accessible area
	(like /usr/local/xsky/db/)

15)  place the binary database files in a publicly-accessible area
	(like /usr/local/xsky/db/).  note that the still-empty *.bin
	files, for catalogs you don't have available, can simply be
	deleted

16)  place the XSky resource file in a publicly-accessible area
	(like /usr/local/xsky/env/)

17)  re-edit xskyenv to change the xxx_PATH variables to point to where the
	*.dat files were placed

18)  re-edit xskyenv to change the xxx_BIN variables to point to where the
	*.bin files were placed

19)  place the new xskyenv in a publicly-accessible area (like
	/usr/local/xsky/env/).  don't bother making it executable;
	users will need to source it as in step 5

20)  new users of xsky now need merely

	setenv XAPPLRESDIR /usr/local/xsky/env

		or

	cp /usr/local/xsky/env/XSky .
	(customize XSky to taste)
	setenv XAPPLRESDIR .

		and then

	source /usr/local/xsky/env/xskyenv
	/usr/local/bin/X11/xsky &

	This will:

	a)  read the binary databases into memory
	b)  open the corresponding text databases (they're necessary for
		xsky's information displays)
	c)  bring up the main display
