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

Text File | 1995-07-09 | 9KB | 168 lines

CUSTOMIZING GED2HTML WITH COMMAND-LINE OPTIONS

Ged2html is a Un*x-style program whose default behavior is to read a GEDCOM
file from the "standard input," to create HTML files and possibly directories
as output, and to write any error messages to the "standard error output".
The behavior of the program can be modified in various ways through the use
of "command-line options".  Under Un*x, a program is run by typing its name,
followed by a list of "words," which are the arguments of the program.
The Un*x convention is that command line-arguments that start with "-" are
control flags that modify the behavior of the program.  Control flags can
take parameters, which by convention are the words immediately following the
control flag.

If you run this program under MS-DOS, you can supply command line options
exactly as you would under Un*x.  (Note that the program does *not* recognize
the MS-DOS conventions of control flags starting with "/" and parameters
specified using ":" after the control flag.)  If you run the program under
MS-WINDOWS, then you don't actually have a "command line" on which to
specify the arguments, as it is intended that MS-WINDOWS programs should
pop up a dialog box to obtain their arguments.  I haven't yet been inclined
to do the necessary hacking necessary to make GED2HTML work this way under
MS-WINDOWS, so if you want to run the program with other than the default
options, you need to launch the program from the File Manager, which will pop
up a dialog box into which you can type a command line exactly as if you
ran the program under Un*x or MS-DOS.

Here are some examples of typical command lines and their effect on GED2HTML:

    ged2html myged.ged

        Run GED2HTML on the GEDCOM file "myged.ged", using the
        default options and creating the HTML files containing
        individual information in the current directory (or in
        subdirectories of the current directory).  Also created
        are index files "INDEX.html" and "SURNAMES.html"
        ("INDEX.HTM" and "SURNAMES.HTM" under MS-DOS/MS-WINDOWS).
        If the number of individuals exceeds the default "index width"
        (currently 28), then "INDEX.html" is the root of a
        hierarchical index organized into several files in such a way
        that the total number of entries in each file is less than or
        equal to the index width.  Finally, a textual index file
        "GENDEX.txt" ("GENDEX.TXT" under MS-DOS/MS-WINDOWS) is created.
        This file contains one line for each individual and is
        output in a format suitable for processing by Unix tools
        such as AWK and SORT.  It is intended for the use of network
        indexing software that will automatically collect pointers to
        individual data from a large number of sites and merge them
        into a single master index.

    ged2html -i myged.ged

        Same as above, except that only the individual HTML pages
        are created, and not the "INDEX.html", "SURNAMES.html"
        or "GENDEX.txt" files.

    ged2html -c myged.ged

        Automatic capitalization of surnames is disabled, so that
        surnames appear in the HTML output the same as they do in the
        original GEDCOM file.

    ged2html -w 0 myged.ged

        The "index width" is set to zero, which disables the
        production of a hierarchical index and arranges for all
        individual entries to be placed in the single "INDEX.html"
        file.

    ged2html -w 100 myged.ged

        The "index width" is set to 100.  This results in somewhat
        fewer index files and a shallower index hierarchy than the
        default setting.

    ged2html -i -c -s I1001 I1002 -- myged.ged

        This command specifies that no index files are to be generated,
        that automatic capitalization of surnames is disabled, and
        that HTML output files should be produced *only* for the
        individuals with cross reference ID's (XREF) I1001 and I1002
        in the GEDCOM file.  An arbitrarily long list of ID's can be
        specified after the "-s" flag, so that the "--" option is
        needed to indicate the end of option processing and that all
        remaining arguments are to be regarded as the names of GEDCOM
        files.

    ged2html -d 100 myged.ged

        Cause the individual HTML files to be placed in subdirectories,
        with a maximum of 100 files per subdirectory.  The hyperlinks
        (URL's) placed in the HTML output files take the directory
        organization into account.  This means that once you process
        a GEDCOM file and create a tree of directories and HTML files,
        you must preserve the organization of this tree if you want a
        WWW browser to be able to traverse the links between the files.

    ged2html -d 0 myged.ged

        Specifying "-d 0" disables the use of subdirectories, so that
        all individual HTML files are placed in the current directory.

Hopefully, you get the idea...    Here are a list of all the options currently
understood by the program:

ged2html [-Hcgiv][-d <files-per-directory>][-n <indivs-per-file>][-s <individual> ...][-f <file-template>][-t <individual-template>][-T <index-template>][-w <index-width>][[--] <gedcom-file> ...]
 -H                     Print a brief message listing the available options.
 -v                     Print version number of program and copyright info.
 -c                     Disable automatic capitalization of surnames.
 -d files_per_directory Specify number of files per subdirectory
                        (0 means don't use subdirectories).
 -f file_template       Specify a template string for the names of the
                        HTML files (default '%s.html' or '%s.htm').
 -g            Force production of the textual index file (for use by
            automatic indexers).
 -i                     Do not generate index files containing entries
                        for all the individuals and surnames in the input.
 -n indivs_per_file     Output files contain specified number of individuals
            (0 means don't put multiple individuals per file).
 -p depth               Include pedigree charts of the specified depth
            (0 means don't include any pedigree charts).
 -s individuals ...     Limit the production of output files to a specified
                        list of zero or more selected individuals.
 -S surname_template    Specify a template file for surname index.
 -t individual_template Specify a template file for individuals.
 -T index_template      Specify a template file for individual index.
 -w index_width        Create hierarchical index of specified width
            (0 means put all individuals in one index file)

One of the features of GED2HTML is that output processing is completely
controlled by user-specifiable programs, called "templates".  Templates are
written in an awful programming language I designed specifically for this
purpose.  Default templates, for the individual index, the surname index,
and for the individual data files, are preloaded into GED2HTML when it is
compiled.  Samples of the default templates have been provided for you in
the files "index.tpl", "surname.tpl", and "indiv.tpl".  If you are happy with
the output produced by the default templates, there is no reason for you to
change them.  However, if you wish to modify the format of the output files
in some way, you can use the "-T", "-S", and "-t" options to specify
alternative template files.  For example:

    ged2html -t indiv.tpl -T index.tpl myged.ged

specifies that "indiv.tpl" is to be substituted for the preloaded individual
template and that "index.tpl" is to be substituted for the preloaded index
template file.  Since these files are supposed to be identical to the
preloaded ones (unless I forgot to update the samples), the command above
should have the same effect as simply saying:

    ged2html myged.ged

On the other hand, if you edit "indiv.tpl" and "index.tpl" to create
files, say, "myindiv.tpl" and "myindex.tpl", then you can say:

    ged2html -t myindiv.tpl -T myindex.tpl myged.ged

and get your own customized output.

If you want to create your own templates, feel free to try it, but be
forewarned that I have not made much of an attempt to make template programming
"idiot proof".  It is my expectation that most people will use the preloaded
templates, and that if you want to make changes to the templates, you probably
ought to be a programmer and you probably ought to read the output interpreter
code in the file "output.c" to see exactly what the interpreter can and
cannot do.  Otherwise, you can just play around making changes to the template
files, using the code in the samples as a guide, but I make no guarantee that
the program won't crash or otherwise behave strangely if you load in a
malformed template.