

                 GEDView 1.05 - Beta test release - 5 Mar 1995
                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


               USAGE: GV [-n] <filename> [scriptname [argument]]



            The GEDCOM data format  was developed by the LDS Church as a
       way to exchange genealogical data between two systems.

            GEDView does this:

                 * indexes, searches and displays GEDCOM database files,
                   even large ones, very quickly,

                 * organizes each record into a readable format,

                 * easily accesses related records by tabbing to or
                   clicking on a GEDCOM "pointer" in the current record,

                 * translates tag names (field names) into descriptive
                   words or phrases.

                 * toggles between GEDCOM or "enhanced" display mode,

                 * saves or appends selected records to file in GEDCOM
                   or "enhanced" style,

                 * has the facility to generate user-designed reports
                   through its script command set,

                 * supports color monitors and a Microsoft mouse,

                 * accepts commands via pull-down menus, mouse buttons,
                   textual prompt-style commands or scripts.


       SPECIFICATIONS
       ~~~~~~~~~~~~~~
            I used the specifications for the proposed GEDCOM  standard,
       draft release 5.3.

            Not  all  GEDCOM files are created equal.  In fact, some are
       downright inferior.  For that reason, GEDView may not work on all
       files purported to be GEDCOM.

            GEDView will handle

                 * files sizes up to 2 gigabytes and will read as many
                   records as can be squeezed into that,

                 * records up to 32,000 bytes in length,

                 * scripts having up to 8,000 lines.

            GEDView was written to be fast.  It will  index  and  create
       look-up  tables  at the rate of about 10 seconds per megabyte and
       will do a global search  in about 8 seconds per each megabyte (as
       performed by on my 386DX-33).


       Please note the following
       ~~~~~~~~~~~~~~~~~~~~~~~~~
            Tag names that are not described by GEDCOM  draft  5.3,  are
       displayed in caps, preceded by an asterisk (*).

            GEDView will create several new files for *each* GEDCOM file
       that is read -- and they  are  not  deleted when the program ends
       (the -n switch can be used on the command  line  to  suppress the
       indexing of an already indexed file.) Be sure
       there is plenty room on your disk.


       WRITING SCRIPTS
       ~~~~~~~~~~~~~~~
            I have a text editor in the works and will make it available
       in a future release.   In  the  meantime,  GEDView scripts can be
       written using any editor or word processor  -SAVED  AS  AN  ASCII
       FILE.

            GEDView  does  very little syntax error checking. And I have
       done little to discover  the  results  of  bad  code.   For  that
       reason,  I  must  insist on the standard disclaimer.*   The  best
       advice  I  can give right now is to be careful.  A poorly-written
       script, can cause any  number  of "undefined" conditions, such as
       freezing your system.

            Although the basic core or engine of GEDView  is  very  fast
       and  efficient, its scripting capability is _very_ slow and needs
       more work.  And, although  the  script  command  set  is  greatly
       expanded  in  this  version,  it  is  still   rather  clunky  and
       simplistic.

            A script  name  and its argument may be specified at the DOS
       command line:

                      GV -n SAMPLE.GED INDENT.PRG SAMPLE2.GED

            That command will start GEDView, will not index (because the
       -n  switch is used -- an accurate index is  presumably  known  to
       exist) and will start up the script INDENT.PRG.  The output file,
       SAMPLE2.GED, will be  created.  The  program can be automatically
       terminated by including the GEDView command, QUIT.

            The script commands are found in the Help menu.

                * Always conclude your script with an END statement.

                * The resulting <action> of an IF statement must go
                  on the next line.

                * Do not call a script from within another.

                * GOSUBs can be nested, DO-REPEATs cannot be nested.

                * Variable names ($ARG, $FULLNAME, $COUNTER, etc.) must
                  be capped.  Otherwise, case does not matter.

                * The  system must have sufficient memory resources  for
                  the  system  command.   The DOS sort, for instance, in
                  SDX.PRG will easily fail.


       Return Values
       ~~~~~~~~~~~~~
            Most GEDView functions will return a value. The FAILED value
       can be thought as being 0, no, negative, unsuccessful, not equal,
       etc.  The  EQUAL  value  can  be  thought of as yes, 1, positive,
       successful, etc.

            If a GEDView command  is  not successful, the FAILED flag is
       set. --  An  IFFAILED  will  check  the  status  of  the  command
       IMMEDIATELY preceding it.  Therefore, nothing, not even a
       GOTO,  comment  or  a  label  can come between the two lines (the
       command to be checked and the IFFAILED).

            Failed (0) and equal (1) can be returned from a GOSUB as
       an argument of the RETURN statement:

                      RETURN 1

            Below is the INDENT.PRG  sample  script.  To invoke it, type
       RUN INDENT.PRG at the dot prompt or select  Run  Script  from the
       Reports  Menu.   An  output  file name may also be included. If a
       file name has not been  given,  INDENT.PRG will create a new copy
       of the opened GEDCOM file with the name NEW.GED.   Each line will
       be  indented by 2 spaces times the line's level.  For instance, a
       level 2 line will be indented by four spaces.

            If your program is recursive  -- that is, returns to the top
       over and over -- you must check for a failed condition to end the
       execution.  Otherwise,  you  will  be stuck in an "infinite loop"
       and will probably have to reboot your system.

            Remember,  GEDCOM files  can  be  very  different  from  one
       another.  Because a script may work for one GEDCOM  it  will  not
       necessarily work for another.

       --

            set bell off
            remember record
            compare $ARG
            ifequal
                    goto set-default-name
            set #outfile $ARG
            save $OUTFILE ""
            go 1

            :the-top
                    show creating $OUTFILE ....
                    get line
                    iffailed
                            goto the-end

            :do-record
                    set #counter -1
                    gosub check-level
                    append $OUTFILE $LINE
                    append $OUTFILE "\J"
                    get next line
                    ifequal
                            goto do-record
                    next
                    iffailed
                            goto the-end
                    goto the-top

            :the-end
                    go record
                    set bell on
                    end

            :check-level
                    add 1 #counter
                    ifescape
                            goto the-end
                    compare $FIELD1 $COUNTER
                    iffailed
                            goto check-level
                    do $COUNTER
                            append $OUTFILE "  "
                    repeat
                    return

            :set-default-name
                    set #outfile new.ged
                    save $OUTFILE
                    go 1
                    goto the-top


            These scripts are included in this release.  They are
       simple   examples   intended   only   to   illustrate   GEDView's
       capabilities. Improvements will be  included  in  future releases
       and/or   archived  in  a  presently-undetermined   directory   at
       genealogy.emcee.com.  I'll be happy to include additional scripts
       of merit in my FTP site.


                      AHNEN.PRG creates ahnentafel for INDI
                      FATHER.PRG displays father of INDI
                      FGS.PRG creates Group Sheet for FAM
                      FLINE.PRG displays earliest paternal ancestor
                                for INDI
                      HTML.PRG creates Web page for FAM
                      INDENT.PRG  <arg>  created  indented  GEDCOM  file
                      MOTHER.PRG displays mother of INDI
                      SAVE-ALL.PRG  creates  file  in  'enhanced' format
                      SDX.PRG   creates   and   sorts   Soundex   report
                      SEARCH.PRG <arg> creates file of records with
                                matching argument


       UPCOMING RELEASES
       ~~~~~~~~~~~~~~~~~
            The basic plan for GEDView is to keep it small and fast
       but to give it the capability for virtually unlimited flexibility
       through scripting and other features.

            These three points will be at the top of the list:

                 * Further improve the core speed.

                 * Greatly increase GEDView's script performance and
                   enhance the command set.

                 * Fix bugs.

                 * Improve the doc.

                 * Internal sort.

            Some intended features include:

                 * Pop-up directory listing.

                 * Configurable default data directory.

                 * Hot-key definitions and macros.


       RELEASE HISTORY
       ~~~~~~~~~~~~~~~
            1.00 - 4/8/94
                   Early unofficial pre-beta in limited circulation.
            1.01 - 7/5/94 First beta release.
                   Added keys to Viewer
                   Redesigned buttons
                   Incl command SET PRINT
                   Added help button
            1.02 - 7/20/94
                   Revised to update FAT table after file creation.
            1.03 - 8/3/94
                   Fixed F10/Next freeze-up.
            1.04 - 8/24/94
                   Another freeze-up fix.
                   Fixed  script  command  IF  FAILED for NEXT  /  PREV.
                   Modified "formatted" mode for save.
                   Fixed SET EOL command.
            1.05 - 2/24/95
                   Clears screen when terminated.
                   Changed  Save  /  Append  hotkeys  to  F4 and alt-F4.
                   Search is no longer case sensitive.
                   Many bugs fixed.
                   Several new script commands.
                   IF FAILED changed to IFFAILED.
                   REMEMBER $RECORD changed to REMEMBER RECORD.



            I have  made many changes  in  the  last  couple  of  weeks,
       particularly relating to scripting.  There has not been much
       time  to  thoroughly  test  the  results.   Undoubtedly,  various
       situations  will arise that had not as yet been contemplated.  It
       will be a big help to  me to have any and all bugs reported to me
       via email.

       Michael Cooley, Mar 1995
       email: michael@emcee.com

       * This  version  of GEDView is neither commercial  nor  shareware
       software  but  is  freely distributed under the terms, conditions
       and understanding of the following: GEDView is still in the early
       stages of development and has been tested  on  only one machine -
       mine.  Any  number  of  conditions can be present - including the
       manufacture of equipment  and  the  operators  mood  -- which can
       influence the performance of this program.   Therefore, I bear no
       responsibility  for  loss  of  data  or  damage  to  equipment or
       operator's personality  resulting  from the use of GEDView and/or
       its by-products.  The user uses at his/her own risk.
