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.