DP Tool Club 24/CD_ASCQ_24_0995.iso/vrac/ged2ht23.zip/README

Text File | 1995-07-09 | 11KB | 228 lines

              A GEDCOM to HTML Translator
          Version 2.3 (July 4, 1995)

               Gene Stark
              ([e-mail])

             Dept. of Computer Science
            SUNY at Stony Brook
             Stony Brook, NY 11794-4400

This program reads GEDCOM files as input and produces a set of HTML files,
each file containing information from one or more individual records in
the GEDCOM input.  The information for each individual contains hypertext
links (relative URL's) to the files for the parents, spouses, and children
for that individual.  Birth, marriage, and death events are included in the
file, as are notes records associated with the individual, and also certain
source information.  A sorted, hierarchical index can also be created, with
a hypertext link to each individual.  The program can be instructed to include
"pedigree charts" with each individual, to facilitate navigation between
individuals.  The program can also automatically insert additional HTML text
into each individual file.  This feature can be used add additional text,
images, audio, or whatever else you want to each individual.  Moreover, you
only have to create the "include files" for the individuals on which you have
extra information, and you can maintain all your other data on whatever system
you are using to produce the GEDCOM output.  If you get an updated GEDCOM file,
simply go to the directory where the individual "include files" are stored and
run "ged2html" again.  It will update each individual file with the new GEDCOM
data and will automatically insert the additional HTML text from the "include
files" again.

I wrote this program because I tried the GEDCOM to HTML translator posted
by Frode Kvam ([e-mail]), and found it insufficiently flexible.
Since his program only parses a limited portion of the GEDCOM file, not
including notes records, there wasn't an easy way to modify it to get
all my notes into the output files.  So, I decided to write a YACC-based
parser for the GEDCOM standard, and to base the translator on that.
The YACC parser was used in version 1 of my program, however as I got
more experience with the GEDCOM standard and how it is actually used in
practice, I decided that it was too difficult to make the YACC-based parser
accept the full variety of GEDCOM's that actually exist.  So, for the current
version I have rewritten the parser so that it will accept essentially
"any" GEDCOM file, and will only complain about grossly malformed input.

I have tested this program on a large number of GEDCOM's, including the
following:

    * The "royal92.ged" file from ROOTS-L, which contains 30,682
        lines of GEDCOM and 3,010 individuals.

    * The "Richard Austin database" (produced by PAF 2.3), which
        contains 82,874 lines of GEDCOM and 6,482 individuals.
        This database was provided to me by Bill Minnick
        ([e-mail]).

    * A database (produced by Family Scrapbook), which contains
        30521 lines and 2121 individuals.  This database was
        provided to me by Bill Spurlock ([e-mail]).

    * All the databases on Yvon Cyr's Acadian/French Canadian CD-ROM.

    * A number of other databases provided to me by users of earlier
        versions of this program.

Small GEDCOM's of under 1000 individuals are processed into HTML by GED2HTML
in a few seconds on a modern PC running Un*x (processing is somewhat slower
under MS-DOS due to the inefficient filesystem).  However, on a system with
sufficient swap space and main memory, much larger GEDCOM's can be processed.
The program is capable of processing all the GEDCOM's on Yvon Cyr's
Acadian/French Canadian CD-ROM.  The largest database I have attempted is the
file "t-roux.ged" on that CD-ROM, which is a 5478458 byte, 214266 line GEDCOM
file containing 15472 individuals and 7012 families.  On my system (486/33
with 16MB RAM and IDE disks, running the FreeBSD 2.0.5 operating system),
it took roughly 35 minutes to process this file, of which under five minutes
was spent reading the file and constructing the database, and the remainder
was spent in outputting 1548 HTML files of individual data, 10 individuals per
file, organized into 31 directories, a three-level hierarchical index
consisting of 574 HTML files, and a surname index in a single HTML file.
The HTML output files consumed 18738K of disk space.  The processing itself
required 32MB of virtual memory.

I have used this program to prepare my own data for presentation on the
World-Wide Web.  You can view this data by starting from URL

     http://www.cs.sunysb.edu/~stark

and following the links.  I preprocessed my GEDCOM file to produce
approximately 700 individual files, which are linked together between
themselves and to my hypertext family history document.  Birger Wathne
([e-mail]) and others are using various versions of this
program in various demonstrations of genealogy over the World-Wide Web.
Many of these demonstrations do not preprocess the data into HTML files,
but rather use LifeLines to manage the database in GEDCOM format, and
ged2html to process the output of queries for presentation over the Web.

I have developed and run this program on an Intel 486DX/33 under the
FreeBSD operating system.  If you using another flavor of Un*x, you
shouldn't have too much trouble getting it to run.  You do need an ANSI C
compiler (like GCC), as I am no longer interested in writing old-style C.
I have also compiled the program for MS-DOS and MS-WINDOWS using Microsoft
Visual C/C++ 1.0.  See the file MSDOS for differences in the default behavior
of the MS-DOS/MS-WINDOWS and Un*x versions of this program.

The GEDCOM parser in the program is built around the GEDCOM 5.3 standard.
Whereas version 1 of this program checked the GEDCOM input fairly stringently
for conformance to the standard, the current version attempts to make sense
out of anything that looks remotely like a GEDCOM file.  It will complain about
grossly malformed GEDCOM files, but it still tries to get through to the
end and produce whatever output it can.

The output processor is template-driven.  That is, it consists of an
interpreter for a simple macro language, which produces output files by
processing template strings and filling in information from the GEDCOM
database.  The template-driven output scheme was used to obtain flexibility
and language independence.  The default templates use the cross-reference ID's
in the GEDCOM file to name the HTML files, and will insert one "image" file
(if it exists) near the beginning of each individual file and one "additional
information" file (if it exists) at the end of each individual file.
For example, an individual with cross-reference ID "I101" would receive an
HTML file "I101.html".  As this file is created, the file "I101.img" would be
inserted near the beginning, and the file "I101.inc" would be inserted at the
end.  Default templates are compiled into the program, and they will be used
unless you specify an alternative template using the appropriate command-line
argument.

If you like the default output format, and you are happy with English as
the output language, then there is no need for you to understand anything
about the template macro language.  This is a good thing, because the
macro language is not that pleasant to program in.  If you do want to
write your own templates, have a look at the files "indiv.tpl", "index.tpl",
and "surname.tpl".  These use most, if not all, the available constructs
in the output language.  A template file consists of text interspersed
with variable references and control commands.  Variable references start
with "$", and are used to insert in-line information from the GEDCOM database.
Constructs that can appear in variables are as follows:

    @        denotes the "current individual" or "current index"

    [i]        is a subscripting operation that selects the i-th
            family, event, note, etc. in a list.  The identifier
            i is an "index variable", which takes on values
            1, 2, 3, etc.

    .fieldname    is a selection operation that follows associations
            in the database.  For example ${@.FATHER} denotes
            the individual record corresponding to the father
            of the current individual.  You have to look at
            the sample template files and the code in output.c
            to see what selectors are understood.

    .&        is a selection operation that turns an individual
            record or index node into a URL to be output in an
            HTML anchor.

    i        refers to the index variable i.

    {}        appearing in a variable name act as delimiters.
            They must be properly matched.

Control constructs are signalled by a "!" appearing at the beginning of
a template line.  The control constructs are:

    !IF condition
    !THEN
    !ELSE
    !ENDIF

The above constructs provide for conditional output based on whether
particular fields in the database have non-null values.

    !WHILE condition
    !END

These constructs provide for repetitive output of a particular section of
the template, based on what is in the database.  For example, it can be
used to iterate over all the marriages of a particular individual.

In both the !IF and !WHILE constructs, the "condition" is a variable,
only without the $ that would normally precede it if the variable were
to appear in normal text.

    !RESET index_variable

Resets the value of an index variable to 1.

    !INCREMENT index_variable

Increments the value of an index variable.

    !NEXT

Advances "@" to refer to the "next" individual or index in the database.

    !INCLUDE filename_template

Any occurrences of "@" in the "filename_template" are replaced by the
cross-reference ID of the current individual (use "@@" to get "@" into
the filename without replacement).  The substituted template is then used
as the name of a file to be included in the output stream.  If the file
does not exist, this construct is ignored.  The included file is inserted
verbatim into the output stream; no macroprocessing is performed on it.

    !PEDIGREE indiv_variable

Causes a "pedigree chart" of the default depth (specifiable by a command-line
option) for the specified individual to be inserted into the HTML output file
at the current position.  Except for the depth parameter, the format of the
pedigree charts is not user-customizable.

I have organized the program so that it is language-independent, except for
the tables in "tags.c".  All strings in the output come either from the
templates or from those tables.  If you want to make the program produce
output in another language, have a look at "tags.h" and "tags.c" to see what
to do.  You should also change the compilation flags in "Makefile".  At the
moment, only English is supported.  If you create tables for another language,
I'd appreciate receiving them so that I can integrate them back into the
source.  Thanks!

THANKS: go to Birger Wathne for contributing useful ideas and code, and to
a number of other users (including Allyn Brosz, Susie and Kerry Jane Dunavant,
Bob Fieg, Steve Messinger, and Doug Smith) of earlier versions of the program
who took the trouble to send me their bug reports and problematic GEDCOMS as
well as their kind words that make all the work I did on this program
worthwhile.

                            Gene Stark
                            [e-mail]