     ===================================================================
                     MANUAL file for Geni Version 1.20
     (c) Martin Dunstan  (mnd@dcs.st-andrews.ac.uk)  February 16th, 1997
     ===================================================================

Credits:
   Idea and design: Vivienne S. Dunstan
   Programming:     Martin N. Dunstan


Features:
   * Databases stored in compact format e.g. 4000 individuals in 300K.
   * Browse to parents, siblings, children or spouses via a few
     easy-to-remember keypresses.
   * Ancestral tree display (three or four generations visible).
   * Zooming on tree display and an optional status window.
   * View details of current individual and their marriages.
   * Context-sensitive help as well as detailed help.
   * Searching with wildcards.
   * Remembers details of recently used databases.


Description:
   Geni is a fully-fledged genealogical database browser for the Psion 3a
   and 3c. It is intended to be used by genealogists who maintain their
   data on a computer such as a PC or Macintosh using a package designed
   for the purpose. Users must be able to save their data in GEDCOM
   format for Geni to work.

   The databases used by Geni are very compact (usually half the size
   of the GEDCOM from which they were created) allowing the user to
   carry large databases on a small Psion without the need for extra
   disks. These databases are created from GEDCOM files by RdGed, a
   program which accompanies the Geni distribution. 

   Users are not expected to keep the Geni file completely up-to-date
   with their central database but will recreate it when needed. The
   ability to save information in GEDCOM format is required for the
   creation of the Geni database file. 


Context-sensitive Help:
   Context-sensitive help is available at all times by pressing HELP.
   This will bring up a small window listing all the available key
   presses. More detailed help can be obtained via the "Info" menu.


Ancestral Tree:
   The program begins by displaying an ancestral tree for the current
   individual. This is either the first individual in the database or
   the one which the user was at when the database was last used.

   The ancestral tree display shows the current individual
   and their parents and grandparents; the lifespan of each person is
   given for clarity. From this screen users can browse to the parents,
   children, siblings or spouses of the current individual via a few
   easy-to-remember keypresses. Alternatively a detailed display of the
   current individual can be viewed by pressing ENTER.

   At the tree display the following keypresses are available:

        f    make their father the current individual
        m    make their father the current individual
        s    select a spouse to be the current individual.
        c    select a child to be the current individual.
        o    make their older full sibling the current individual.
        y    make their younger full sibling the current individual.
        d    show details of the current database.
      ENTER  show details of the current individual.
      HELP   show the currently available key-presses.
      MENU   bring up the application menu.

   The "o" and "y" key presses browse to the next oldest or youngest
   full sibling where "older" and "younger" is determined by the order
   in which the siblings are listed in the GEDCOM rather than by age.
   Only full siblings are considered - to browse to half-siblings press
   "f" or "m" and then press "c". If the current individual is the oldest
   then the "o" search wraps around to the youngest sibling. Similarly
   the "y" search will wrap around if the current individual is the
   youngest.


Zooming:
   The size of the text used to display the ancestral tree can be changed
   by choosing the "Zoom in" and "Zoom out" menu options. Three sizes are
   available - the medium and large settings just show three generations
   (individual, their parents and their grandparents) while the smallest
   size shows four generations (ie. includes great-grandparents).

   The current zoom setting will be retained after you quit Geni and be
   used as the default level when you run Geni again.

   Zooming is currently not available on the detailed display but will be
   a feature of Geni version 2.00.


Status Window:
   By default the full-size status window is displayed to the right of the
   ancestral tree. Press Control-Menu to make the status window narrower
   and press it again to make it disappear. Pressing it a third time will
   bring it back at full size.

   Geni remembers what type of status window you last used so you shouldn't
   need to keep fiddling with it!


Detailed Display:
   The detailed display shows the birth (or christening) and death (or
   burial) of the individual and two scrolling lists. The first scrolling
   list contains all the spouses of the current individual while the second
   contains all their children by all those spouses. The up and down cursor
   keys scroll through the currently selected list and the left and right
   cursor keys shift the list contents from side to side; the user can switch
   between the two scrolling lists by pressing the TAB key.

   To view the marriage details of the current individual and the currently
   selected spouse press the "m" key. Press Escape or Enter to get rid of
   the marriage details.

   Pressing ENTER will browse to the highlighted individual in the currently
   selected list (either the spouse or a child of the current individual) and
   show their ancestral tree. As with the tree display, HELP provides context-
   sensitive help and MENU brings up the application menu.


Searching:
   Individuals may be searched for by name from the menu. Searching is
   case insensitive and limited pattern matching facilities are available
   via the * and ? symbols. The * will match zero or more characters while
   the ? matches any single character. For example, to find someone called
   William Gordon with unknown middle names (or even no middle names) the
   pattern "william*gordon" could be used. To search for someone whose
   name might be spelt as Elizabeth or Elisabeth the pattern "eli?abeth"
   should be used.

   Surnames in Geni are enclosed in two slashes (/). This enables the user
   to just search on a surname if they wish. For instance, to find the
   first person in the database with the surname ROBERTS you should search
   for the text "*/Roberts/". To find the next person in the database with
   that surname use the "Find Again" menu option.

   Note that Geni always adds a * after the pattern you type so "b*sM?th"
   matches "Fred /Blacksmith/ Jr" as well as names such as "Barbara Smith"
   and "Basmyth".

   There are no facilities for querying relationships or for searching for
   people using anything other than their name. It is hoped that these
   facilities will be available in version 2.00 of Geni.


Editing Data:
   There are no facilities for altering the information stored in the
   database except by modifying the original GEDCOM file and recreating
   the database with RdGed. Version 2.00 of Geni may have an option of
   attaching notes to individuals for use in libraries and record offices.


Multiple databases:
   Geni supports multiple databases although only one may be viewed at
   a time. Various details of recently used databases are remembered
   such as the current individual and search string so users can quit
   the application and restart at the point where they left off.


Installation Guide:
   The following notes assume you have enough memory to install Geni and
   RdGed as well as storing the GEDCOM and the Geni database file at the
   same time (see the Footprint section near the end of this file). If
   you are limited for space you can leave the GEDCOM on your main computer
   and access it via the serial link. If you are very short of space you can
   direct RdGed (via the dialog windows) to store the Geni database on your
   main computer until after installation.

   Make sure you are at the system screen and not inside an application.

   Now check that the RunOPL application is installed: hold down the Control
   key and press the Calc icon on the button bar (above the 9 and 0 keys).
   If you can see an icon in the shape of a speech bubble on a transparent
   background with the word "OPL" inside then RunOPL is installed. The
   Program application looks similar but has a dark background.

   If you can't find RunOPL and get the message "RunOPL not installed" then
   you should install it as follows:

     * Press the MENU button and use the left or right arrow keys to move
       to the "Apps" menu. Use the up or down arrows to select the "Install
       Standard" option and press ENTER.

     * A dialog box will appear with a name between two arrows. This will
       probably be RunImg but might not. Use the left or right arrow keys
       to find RunOPL. Once found press ENTER and the RunOPL icon will
       appear on the screen.

   Now make sure that the \OPO directory is created: select the Time icon
   and press TAB. Since the Time application has no files you should see
   a listing of the \ directory. Use the up arrow to see if \OPO is listed.
   If not press the MENU key, move to the "Disk" menu and select "Make
   Directory". Type in \OPO as the dirctory to be created.

   The distribution files (GENI.OPA, GENI.HLP, GENI.PIC and RDGED.OPO)
   can be installed on any drive. You can even split the distribution
   over multiple drives (eg. GENI.OPA on A:, GENI.PIC on B: and GENI.HLP
   on the internal drive) if you are short of memory.

     (1) Create the following directories:
           \APP\GENI
           \GENI
           \GENI\GED

     (2) Make sure that your transfer program regards .HLP files as
         binary files and .GED files as plain text files.

     (3) Copy:
           GENI.OPA  into \APP
           GENI.HLP  into \APP\GENI
           GENI.PIC  into \APP\GENI
           RDGED.OPO into \OPO
           Your GEDCOM file(s) into \GENI\GED

     (4) Choose INSTALL from the system screen APP menu and install Geni.

     (5) You can now run RdGed on each GEDCOM file to convert them into
         Geni files: see the tutorial section below for more help. Once
         RdGed has finished converting the newly created files can be
         used by Geni immediately.

   After conversion you can remove the GEDCOM files and RDGED.OPO as well
   as \GENI\GED if you created it. RdGed can read GEDCOM and write Geni
   databases over the serial link - at either of the dialogs press the down
   arrow and then use the left and right arrows to select the appropriate
   drive. Unfortunately Geni doesn't like to access the databases over the
   serial link so you must have them stored on the Psion somewhere, ideally
   in \GENI.

   The detailed help information is stored in the GENI.HLP file. If you
   need a little extra space this file can be deleted and Geni will still
   work although detailed help will be unavailable (context-sensitive help
   is always available though). You can also delete the GENI.PIC file if
   you want but then you will get a fairly boring title screen!


Using FtGedFix:
   This ONLY applies to users whose GEDCOM was created by the Family Tree
   program. This program outputs GEDCOM which few genealogy programs can
   understand and the purpose of FtGedFix is to convert Family Tree GEDCOM
   into a format acceptable to RdGed.

   If you have Family Tree GEDCOM then run FtGedFix in exactly the same
   way as RdGed (see the next section) and then run RdGed on the GEDCOM
   FtGedFix produces.


Using RdGed:
   This is a short tutorial to familiarise yourself with using RdGed.
   Start by installing Geni and RdGed as described in the previous
   section and copy DEMO.GED into the \GENI\GED directory.

     (1) From the system screen find the RunOPL application which should
         have RdGed listed as one of its files. Use the arrow keys to
         highlight RdGed. If RdGed isn't listed and you have definitely
         copied RDGED.OPO into the \OPO directory try pressing the System
         button (leftmost icon on the button bar).

     (2) Start RdGed by pressing ENTER and then use the dialog box that
         appears to select the GEDCOM file you wish to convert. If the
         DEMO.GED file hasn't been copied into \GENI\GED then press the
         TAB key and locate it using the standard Psion file browser.

     (3) Press ENTER and then type in the name of the Geni file to be
         created at the second dialog box that appears. If you have
         already created a Geni file with the same name and wish to
         overwrite it it may be quicker to press the TAB key and then
         use the arrow keys to find it. For the moment type in "DEMO".

     (4) When ready press ENTER. If the Geni file specified already
         exists you will be asked if you want to overwrite it - either
         answer yes to continue or no if you wish to enter another name.

     (5) A progress indicator should appear showing how much of the
         file has been indexed. When the indicator reaches the right
         edge it will be replaced by one showing how far the sorting
         has got. This indicator will start slowly before speeding up.
         Due to the way the index is sorted the indicator will probably
         not reach the right edge before it vanishes.

         The final indicator shows how far the conversion process has 
         got based on the number of bytes read from the GEDCOM file.

     (6) When the conversion is complete a small dialog box is displayed
         informing the user of the number of individuals and families
         that were found. Press ENTER or ESCAPE and RdGed will finish.

     (7) Now locate the Geni icon on the system screen. It should have
         the name of the newly created database below it (DEMO). If not
         press the System button and it should appear. Move the highlight
         onto it and then press ENTER to start Geni.

     (8) Everything should be self-explanatory from this point onwards.
         If you can't remember a key press then use the HELP key to get
         context-sensitive help. For more detailed information select
         the "Info/Help" menu option.


Notes:
   The Geni databases must be created using the RdGed program that comes
   with this distribution. This program accepts a GEDCOM file as input
   and will produce a compact database that Geni can read. I have tried
   to make RdGed as resilient as possible and it should be able to
   swallow any type of GEDCOM that is thrown at it. This is achieved by
   the ostrich approach (if a line isn't recognised it will be ignored
   and we hope it won't matter) and by placing very few restrictions on
   the format of the GEDCOM. The single main assumption is that the INDI
   and FAM records all begin at level 0 but this shouldn't create any problems.

   RdGed is also careful about memory usage: if there isn't enough memory to
   store the rest of the Geni file being converted the user will be prompted
   to either delete files to free up some memory or to abort. It may be
   sufficient to quit all other applications to free enough memory without
   having to resort to deleting files.

   The reason why Geni does not read GEDCOM directly (like Gedfried does
   for example) is because of the speed of parsing and the size of the
   GEDCOM file. At the moment the author is able to translate GEDCOM into
   the OPL database at a rate of 1.3 records (INDI or FAM) per second when
   both files are stored in main memory. When the GEDCOM and OPL databases
   are accessed over the serial link (necessary for very large GEDCOM
   files which might not fit onto a single flash disk) this drops to
   around 0.8 records per second. 

   Since my wife has a 700K GEDCOM database containing under 6000 records,
   processing time is over an hour and the GEDCOM won't fit onto her 1M
   Psion! The conversion process usually produces a file about half the
   size of the original GEDCOM which should easily fit on a small Psion
   (my wife's database easily fits onto her 1M Psion with any disks).

   Users are expected to use RdGed infrequently so the inconvenience of
   having to create a special database for their Psion should be offset
   by the advantages of being able to take the information into places
   such as record offices and libraries in such a compact format. 


RdGed 1.11 Footprint:
   System memory (running) ... 22K
   User memory (running) ..... 13K
   Application size .......... 15K
   Total ..................... 48K

   If large GEDCOM files are converted then some extra memory might
   be needed for a lookup table. A database of 6000 records could
   require an extra 64K of system memory.


Geni 1.20 Footprint (from DEMO.GED):
   System memory (running) ...  25.0K
   User memory (running) .....  22.0K
   Application size ..........  27.2K
   Help database .............   4.9K
   Title screen ..............   7.1K
   Resource file .............   1.0K
   Extra (detailed screen) ...  27.0K
   Total ..................... 114.2K

   The operating system requires some extra memory when opening new
   Geni databases. This memory is released once the database has been
   successfully opened. For a database of about 380K the extra memory
   is about 20K.


Bugs:
   No bugs have been found in this version although there must be some
   lurking somewhere. If you do find any bugs or the program crashes
   with a fatal error please let me know! Ideally I need to know the
   exact circumstances under which the bug appears so try and restart
   the program and replicate the bug using the least number of moves.

   RdGed also seems to be free from bugs - if you find any please send
   me a fragment of GEDCOM that is causing the problem. The program will
   attempt to tell you which line it stopped at but it is probably best
   to look at the lines immediately before and after it.

     ===================================================================
                     MANUAL file for Geni Version 1.20
     (c) Martin Dunstan  (mnd@dcs.st-andrews.ac.uk)  February 16th, 1997
     ===================================================================
