THIS IS THE MAIN BASE DIRECTORY README FILE
===========================================

David W. Walker
walker@msr.epm.ornl.gov

**** PLEASE READ ALL THIS FILE, AND THE DISCLAIMER FILE IN THIS DIRECTORY ****

PURPOSE OF DISTRIBUTING THIS SOFTWARE
=====================================
I have developed a Motif-based genealogy program. I don't have enough time
to develope it further, so I'm distributing this code with the right to
copy, modify, and distribute (without fee) so that others can help improve
it. If you are interested in furthering this noble objective then we should
establish a mechanism for altering the code in a coordinated way. Please send
suggestions for doing this to me at the email address above.

PREREQUISITES
=============
XFAMILY is a Motif-based genealogy program (really a genealogical database 
browser in its current form). The prerequisites for running this program are 
as follows:

	(1) A Unix system with Motif
	(2) An X program capable of displaying scanned photos or other
	    image files. This viewer must be called "xv" and be callable
	    as follows:
			xv my_file
            where my_file is the name of the file containing the graphical
	    data. The xv program must be in your path.
	(3) An X-based capable of displaying text files. This viewer must
	    be called "fileview"  and be callable as follows:
			fileview some_file
            The fileview program must be in your path.

If you don't intend to look at photos, sources, or notes (see below) then
(2) and (3) are not necessary. In this case, XFAMILY should run on any Unix
system with Motif, in theory. I've only tested it on my IBM RS/6000 
workstation.

The image viewer that I use is THE xv program developed by John Bradley.
This is available from a number of anonymous ftp sites, e.g., 
the file ~gifstuff/xwindows/xv/xv2.tar.Z on bongo.cc.utexas.edu.

The text viewer that I use is from Chapter 9 of Douglas A. Young's excellent 
book "The X Window System, Programming and Applications with Xt: OSF/Motif 
Edition" published by Prentice Hall, 1990. ISBN -0-13-497074-8. The
software from this book may be obtained as file ~ftp/contrib/young.motif.tar.Z
from export.lcs.mit.edu.

INDEX TO DIRECTORY TREE
=======================
Directories are all in uppercase.

             |-DOCS          Transcribed documents such as birth, marriage, and
	     |               death certificates.
             |
             |-NOTES         Note files on individuals
             |
             |-PHOTOS        Image files
             |
             |-SOURCES       One file per person listing files in DOCS
             |               directory that mention that person.
             |
  |-DATABASE-|-family.orig   The XFAMILY database. This example is a drastically
  |          |               pruned version of my family tree.
  |          |
  |          |-xorig, xyob,  These are scripts for running XFAMILY performing
  |          | xsurname      no sorting, sorting by year of birth, and sorting 
  |          |               by name, respectively.
  |          |
  |          |-XFamily       Application defaults file for XFAMILY.
  |          |
  |          |-PSfamily      Script for running PS program for generating
  |          |               version of database.
  |          |
 -|          |-Other files   awk.* and sort.* files are used by the xyob and
  |                          xsurname scripts to sort the XFAMILY database.
  |
  |-MOTIF                    Contains source code for Motif utilities used 
  |                          by XFAMILY.
  |
  |          |-xfamily.c     The source code for XFAMILY
  |          |
  |          |-sourceview.c  The source code for the program used to view
  |-SOURCE---|               the list of files in the DOCS directory related
             |               to a person
             |
             |-PS.c          The source code for producing a PostScript version
                             of the database in "index card" format, 10 people
                             per page.

OVERVIEW OF XFAMILY
===================

XFAMILY reads in the database (all of it since it's not an out-of-core 
program), and displays a scrolled list of names. Type "q" anywhere in this list
to terminate the program at any time. Click on a name and a window
(actually a Motif form widget) on that person pops up. This "person window" has
the person's name as the title across the top, then date of birth,
place of birth, father, mother, date of marriage. place of marriage,
spouse, date of death, place of death, number of children, generation number.
There is also a scrolled list of the children. If there is more than
one marriage there's a button with marriage number in it. Clicking on this
changes the marriage fields to show the next marriage. Once you've gone
through all marriages you get back to the first one. If you click on any person
in the window (i.e. a child, parent or spouse) the personal window for
that person pops up. Along the bottom of each personal window are 4 buttons
labelled:

Discard: This makes the personal window disappear.

Photos : Makes a system call to xv to display images (if any) one
         at a time in a fixed order.
Sources: Makes a system call to the sourceview progam which brings up a 
	 scrolled list of source files in the DOCS directory that refer to 
	 that person. Clicking on one of these will display the source file 
	 (it makes a system call to the fileview program). I'm currently in 
	 the process of entering all my source material into the computer.
Notes  : Makes a system call to the fileview program to list a file in the
	 NOTES directory pertaining to the person. This is used for less
	 official information, e.g. "Grandma says Uncle Joe drank a lot"

RUNNING XFAMILY
===============

Go to the DATABASE directory and key in

	xorig

to run without sorting the information in the database file, family.orig,
in any way. There are also two preprocessors that use Unix utilies to sort into
surname order, or data of birth order. If you key in

	xsurname -s

the preprocessor will sort the family.orig database by name, producing a
sorted database called family.surname. Then XFAMILY will be started using the
sorted database, so the initial scrolled list will be in name order. Once you 
have created the sorted database in this way you can subsequently run XFAMILY
using the sorted database by keying in just

	xsurname


Every time you changed family.orig you must resort to get an up to date
version of family.surname. You can also sort the database by year of birth
by keying in 

	xyob -s

This produces a sorted file, family.yob. If you just want to produce sorted
databases without firing up XFAMILY you can run the scripts sort.surname and
sort.yob.

OVERVIEW OF PS 
==============
PS outputs a PostScript version of a sorted database (family.surname or
family.yob, see above) in "index card" format. Each person's index card is 
4.25 by 2 inches, and they are arranged 10 to a page in 2 columns. The size 
is chosen so the file can be printed on self-adhesive labels. I use Avery 
copier labels (product number 5352) as these jam up the printer less often 
than other labels that I've tried.

RUNNING PS
==========
Go to the DATABASE directory and key in

	PSfamily surname >output_file   (or pipe to printer)

to output PostScript file in surname order, or

	PSfamily yob >output_file       (or pipe to printer)

to output PostScript file in year of birth order. The file family.surname or
family.yob must previously have been created as described above.

OVERVIEW OF SOURCEVIEW
======================
SOURCEVIEW brings up a scrolled list of documents in the DOCS directory
that relate to a specified person. Clicking on one of these documents causes
that document to be displayed in a scrollable window. SOURCEVIEW is called
by XFAMILY but can also by run in stand alone mode.

RUNNING SOURCEVIEW
==================
Go to the DATABASE directory and key in

	sourceview n

where n is the ID number of the person you're interested in. ID numbers are
explained below.

ID NUMBERS
==========
Each person has a unique ID number in the range 0 to 997 inclusive. A person's
ID number is specified in the database file family.orig. If you look in this
file you'll see that each person's name is followed by a number. This is
the ID number. It is actually an index into an array of structures. Thus, the
number of people in the database is currently limited to 998. This can be
changed by changing the quantity MAXNODES defined in the file family.h in the
SOURCE directory.

DATABASE FORMAT
===============
I made up the database format before I'd ever heard of GEDCOM or soc.roots.
The format is pretty self evident if you take a look at family.orig in the
DATABASE directory. Each name is followed by the person's ID number which
must be used consistently. To see how multiple marriages are handled take a
look at John Walker (ID number 241). The generation number is based on me
being in generation 1. 

dob, pob, father, mother, dom, pom, spouse, dod, and pod records can have
the entry "Unknown"

If marriages is 0, then the dom and pom entries should have the
entry "Not applicable".

If a person is still living the dod entry should be "Living" and the
pod entry should be "Not applicable".

There is no way of specifying that a person has at least so many
children, or that a person has fewer than so many children.
The number of children must be a definite integer greater than or equal
to 0.

Dates should be entered as:

	year [month] [day-of-month]

in that order separated by single spaces. The brackets indicate that the month 
and day-of-month are optional. Estimated dates may be entered as:

	year [month] [day-of-month] Estimated

If I only know the baptism date but not the birth date I enter:

	year [month] [day-of-month] (bapt.)

Similarly, if I know the burial date but not the date of death I enter:

	year [month] [day-of-month] (bur.)

XFAMILY will display whatever comes after the year, followed by a comma, and
then the year.

FILE NAMES
==========
The list of files in the DATABASE/DOCS directory that relate to a specified 
person are stored in the DATABASE/SOURCES directory. There is one such list
for each person referred to by a file in DATABASE/DOCS. The filename of
the list is "sources" followed by the persons 4-digit ID number, e.g.,
sources0027 for the person with ID number 27.

Note files are kept in the DATABASE/NOTES directory, and obey a similar naming
convention to source files, e.g., notes0027.

Image files are kept in the DATABASE/PHOTOS directory. The Nth photo of person 
with ID number M is "XM.N.*" where M is 4 digits and N is 2 digits. Thus,
if we have a JPEG and a GIF image of the person with ID number 27 they
would have file names X0027.00.jpg and X0027.01.gif.

IMPROVEMENTS
============
There are any number of improvements that could be made to the code. Here
are a few of the things I'd like to see.

1) Fan-in fan-out plots
2) Circular ancestor charts
3) Postscript output for the above 
4) A "photo album" facility that allows me to browse photos and scanned
   documents.
5) Modify the code to accept Gedcom input. 

INSTALLATION
============

cd MOTIF
make
cd ../SOURCE
make xfamily
make PS
make sourceview
mv xfamily ../DATABASE
mv PS ../DATABASE
mv sourceview ../DATABASE

TESTING
=======
Go to the DATABASE directory and type:
	
	xsurname -s
