(C) The copyright for this document and the accompanying code is claimed by
David Squire, 26th July, 1994. Permission is given for users to use the
code as they see fit, and make any modifications they see fit, for their own
use only. Permission is not given for this code to be distributed except in
the form in which it was received from the author, including this file.

*******************************************************************************

	Xguide - an X windows viewer for Project Galactic Guide articles.

	Author: David Squire	squizz@cs.curtin.edu.au

	Version: beta-1.2.1

	Date:    19930802	(yyyymmdd)

*******************************************************************************
This is a bug fix of 1.2. There are no new features. Only one character of
the source has been changed, but, boy, was it an important one! Sorry to
everybody who stuffed around with the buggy version.
*******************************************************************************

Yes! It's the long-awaited next version of Xguide, jam-packed with new
features....Well, not exactly jam-packed, but there are some. :)
Description of the new stuff is at the end of this file.

********************
Hi all, this is the beta version of this program. The code is not
optimised, and many functions are not yet implemented. This distribution is
intended to give interested persons an idea of what I am doing so that they
can respond to me with comments, criticisms and requests for functionality.

COMPILING:
To compile this on your local system, all the files in this package should
be in the same directory. You will need to have Unix, cc and make, 
Xwindows and the Motif widget set libraries. Simply go to the
directory where you installed the source files and type 'make'. That should
be all that you have to do. Please mail me if this does not work!

I have supplied two prototype files: Cguide_X.proto and Cguide_std.proto.
If you do not change the source, this should be fine. If you *do* change
the source, you will need to run the script 'prmakes'. For this you will
need to have the program 'mkproto'. If you don't have mkproto, you can edit
the prototype files directly.

Note that depending upon the version of cc that you are using, warnings
about incompatible pointer types may be generated during compilation.
These should not affect the running of the program. They are due to my
slightly sloppy way of dealing with some of the types used by Motif. In
future, a few typecasts should fix this :) (They didn't! I think that there
is a problem with prototypes in the header files. If anyone has a solution
to this problem, please let me know!!!).

(I think I might have fixed this - please report any warnings that you get,
and how you fixed them if you did.)

RUNNING THE PROGRAM:
I have included a tiny script called 'XG' for executing the program. This
script merges the resource file 'Xguide.rdb' into the X resource database
to set up colours, fonts, etc. After this has been done once, it does not
need to be done again during the same login session. If you are happy with
the settings in this file, you can include them in the .xrdb file in your
home directory. It will then not be necessary to use the XG script, and the
program, can be run by simply typing 'Xguide'.

The first time you run the program, the screens will be blank, since the
CGD working files will not have been created. Simply select "Create new
Working Files" from the "File" menu. This will create the required files
from the *.NEW or *.new files in the directory. You may have to resize the
window after doing this. Next time you run the program it will load the
files automatically. 

*************************   NOT A  WARNING!!!!!   *****************************
NOTE: At the moment the program will crash if you try to "Create new
Working Files" when there aren't any *.NEW or *.new files in the directory
where Xguide was run. This is a bug which will be fixed in later versions.
The *.NEW files are available via anonymous ftp from vela.acs.oakland.edu
(see the Project Galactic Guide FAQ if you don't know what I'm talking about).

This bug has been fixed, but it still doesn't give you a nice dialog box
explaining what happened. A message is written to stdout.
*******************************************************************************

If you download updated article archives from vela.acs.oakland.edu,
simply place them in the Xguide directory and select "Create new Working
Files" again. Note that at this stage Xguide simply builds new working
files using all the *.NEW (or *.new) files in the directory. It does not
merge them with existing CGUIDE files. This is not the way the final
version of this program will work, but it means that you must have ALL the
*.NEW files in the directory when you select "Create new Working Files" at
the moment.

Articles are selected by clicking on the title in the list on the right
hand side of the window. Cross-references are selected by clicking on the
cross-reference title in the list below the article. Index entries are
selected in the same way.

CHANGING THE FILE: Xguide.rdb
Note that if you make changes to the Xguide.rdb file and then use XG again,
the results may not be exactly as you expect. This is because XG does a
*merge* with the database, not a replace. This means that some things that
you think you have changed may not change due to inheritance from previous
declarations etc. If you are playing around with Xguide.rdb you should
probably change the '-merge' option in the first line of XG to '-load'.
This will replace the entire previous database. This likely to screw up
some of your usual default settings for Xterms and so on, but you can
change it back to '-merge' once you have Xguide looking the way you want.
Everything will be OK the next time you log in.


CONCLUSION:
All sorts of bells & whistles are still to come, such as an article search
function (by Title, Author etc).

Please let me know of any features that you think would be good.

I hope that this is enough to get you going. Good Luck!

Please mail any and all comments to:

	squizz@cs.curtin.edu.au

as soon as you are able.

Thank you for your participation in both the testing of Xguide, and in
Project Galactic Guide itself.

David Squire
(Squizz)

/****** NEW MATERIAL 19940303 *******/
In this version, I have changed the C compiler specified in the Makefile
from 'gcc' to 'cc'. This is because 'gcc' does not work with the latest
version of the Irix operating system on SGI machines. You should be able to
use the compiler you usually use. To change from 'cc' to 'gcc', simply
edit line 2 of the Makefile.

In fact, of late I have had trouble running the program under Irix 5.1.1.2
no matter what compiler I use. There are known bugs with this operating
system, so I am not at all sure that the problem is my fault. If I compile
on an SGI with an older operating system, everything is fine, and the
resulting binary runs fine under Irix 5.1.1.2 . Perhaps you should avoid
Irix 5.1.1.2 - anyone who succeeds with it, please let me know!

An 'Options' menu has now been included, which allows you to specify the
reality levels you want included in the Table of Contents. This state is not
'remembered' when you quit the program - something for the future.
such as "Display only real articles" etc. At this stage this only affects
the table of contents, not the index.

Also new in this version is the index. Please let me know what you think of
the implementation. For instance, would you like to see the title as well
as the index entry in the index list?

/****** NEW MATERIAL 19940726 *******/
Well, the compiler is still cc, but SGI have released a new version of
their operating system, and the bugs that are referred to above seem to
have disappeared. There are several new features in this release. They are:

	Header file to specify directory paths.
		This means that you don't have to run Xguide from the
		directory where the working files are stored. Make sure you
		read the instructions, and edit the #defines in "paths.h"
		before you compile Xguide.

	Ability to create and load Guides with the filename of your choice.
		Yep. Say you want a Guide that only contains "real"
		articles. Just delete (or move) all the *.new files except
		the "real0*.new" ones and select "Create New Working
		Files", give it the name of your choice, and away you go.
		You can then use the "Load" menu option to load which ever
		Guide you want at a given time.

	Ability to specify Date ranges for articles in Table of Contents.
		Just the thing if you've just downloaded some new files
		from the mothership and created new working files, but only
		want to see the new ones.

	Option for bidirectional cross-references to be displayed for articles.
		i.e. If one article cross-references another, then
		the cross-referenced article is given a cross-reference back
		to the original article. You follow that? Note that this is
		optional - you can switch this off so that you don't have to
		wade through the 50 or so cross-references this gives to
		"Earth".

	Some bug fixes.

	Some stuff is now prettier.
		Like, the toggle buttons go orange when selected.

	Maybe some more stuff I've forgotten about.
		It's so long since I uploaded a new version that I way have
		forgotten some of the stuff I've added since March 1994.

SHARE AND ENJOY!

Squizz