		    xsky 3.0.0 - an interactive sky 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 make file
called  Makefile.std  is  provided,  and there's  also an Imakefile which is
discussed below.

If you decide to use Makefile.std, you'll need to edit the  INCLUDES line to
point to  your Athena widget and X  Toolkit header file directory (actually,
it should point to the directory containing the "X11" directory; inside that
is where the header files live).   There is a line defining X11LIBDIR;  this
should point to the directory where your X11 libraries reside.  You'll  also
need  to change the commenting-out in the  definition of X11R6LIBS depending
on whether you're using X11R6 or not.

There  is  no  install  rule  in  Makefile.std; such  a rule is useless  for
individuals, who can't stuff things into the  system  areas  anyway, and the
install utility varies  sufficiently from  system to system that  it's often
useless to the system administrator, too.

After editing Makefile.std, dependency lists should be created with "make -f
Makefile.std depend".  Then issue the command "make -f Makefile.std".

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 .c.a rule, so
you'll need to hang onto all the  .o  files.  And  finally,  if you use gcc,
you'll want to uncomment the appropriate line in the Imakefile.

xsky is known  to compile  cleanly and run under Ultrix cc and gcc; 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, and under the  various free BSD Unices available for PCs.
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, if you used the Imakefile.

The C shell script 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,  then
applied with the command "source xskyenv" before running makebin.

Under  the  Bourne  shell, this  script  is  called  xskyset, and should  be
similarly edited  before  being invoked with the command ".  xskyset" before
running makebin.

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.

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
    317432 ngc2000.bin
     37184 qso.bin
    195920 rngc.bin
   8286792 sao.bin
   8286216 saoj2000.bin
    310568 ugc.bin
    724456 var.bin
   2355528 wds.bin
    291080 ybs.bin
    208776 boundaries.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 knows 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.  Assuming that
you leave  it in same directory as you built xsky, and that you change  your
working  directory to the xsky  build  directory to run  xsky,  the  correct
command,  under the C  shell,  is "setenv XAPPLRESDIR .".  Under  the Bourne
shell, the same thing is accomplished by "XAPPRESDIR=.; export XAPPLRESDIR".

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:

*displaylatinidfont:  *-helvetica-*-*-*-*-10-*
*displaylatinconfont:  *-helvetica-*-*-*-*-14-*
*displaygreekfont:  -adobe-symbol-medium-r-normal--12-*

If those font names don't work for you, you can either change the font names
in XSky,  or comment out those lines in XSky, and uncomment  the lines which
read  simply "helvetica10", "helvetica14", and "symbol12".  Then create font
aliases by those  names (they may actually already  exist) 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 you up and running quickly.  Do this under the C  shell, or be sure
to follow the modified instructions if you're running the Bourne shell.

1)  unpack the kit and read this file; you should also read README.  users
	should read SUMMARY and catalogs.doc

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

	(note that under Digital Unix (nee OSF/1), you'll have to use
	/usr/opt/ultrix/usr/bin/make instead of /usr/bin/make)

	or

    xmkmf
    make depend
    make

3)  source xskyenv
	(under the C shell)

	or

    . xskyset
	(under the Bourne shell)

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

5)  setenv XAPPLRESDIR .
	(this is a C shell command that tells X where to find the XSky
	resource file; "." means the current directory)

	or

    XAPPLRESDIR=.; export XAPPLRESDIR
	(this is a Bourne shell command to accomplish the same thing)

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 README.  users
	should read SUMMARY and catalogs.doc

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

	(note that under Digital Unix (nee OSF/1), you'll have to use
	/usr/opt/ultrix/usr/bin/make instead of /usr/bin/make)

	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
	(this is a C shell command that will cause the definitions in
	xskyenv to be loaded into the shell)

	or

    . xskyset
	(this is a Bourne shell command to accomplish the same thing)

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

8)  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)

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

10)  you now have:
	a)  an xsky executable
	b)  some text database files (*.dat, *.tab)
	b)  some binary database files (*.bin)
	c)  some *.o files
	d)  libsky.a (if you used Makefile.std)
	e)  the XSky resource file
	f)  the xsky icon bitmap file xsky_icon
	g)  the script xskyenv
	h)  the man page xsky.man
	i)  the documentation files SUMMARY and catalogs.doc

11)  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.

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

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

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

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

16)  place the xsky icon file in the directory where your window manager
	expects to find icon bitmaps, or where XAPPLRESDIR is pointed

17)  re-edit xskyenv to change the xxx_PATH variables to point to where the
	*.dat and *.tab 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 6

20)  place the man page, xsky.man, in /usr/man/man1/xsky.1X or
	/usr/local/man/man1/xsky.1X, or whereever your local
	standards dictate

21)  place the documentation files README, SUMMARY, UPDATE, and catalogs.doc
	in a user-accessible place, such as the directory in which the data-
	base files are kept

22)  new users of xsky now need merely

     C shell:

	setenv XAPPLRESDIR /usr/local/xsky/env

		or

	cp /usr/local/xsky/env/XSky .
	(customize XSky to taste - this only needs to be done once)
	setenv XAPPLRESDIR .

		and then

	source /usr/local/xsky/env/xskyenv

     Bourne shell:

	XAPPLRESDIR=/usr/local/xsky/env; export XAPPLRESDIR

		or

	cp /usr/local/xsky/env/XSky .
	(customize XSky to taste - this only needs to be done once)
	XAPPLRESDIR=.; export XAPPLRESDIR

		and then

	. /usr/local/xsky/env/xskyset

     Finally, under either shell:

	/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
