Customizing GED2HTML Output under Windows

When GED2HTML is launched, the dialog box that appears contains blanks for "GEDCOM File" and "Options File". There is a button group entitled "Option Editing", containing buttons "Load", "Edit", and "Save". Finally, there is a field entitled "Additional Options", and a field entitled "Options Summary". (The latter field is read-only.) To cause the program to do anything interesting at all, you at least have to enter the name of the GEDCOM File to be processed in the "GEDCOM File" field. The other fields and buttons are used to load, edit and save options sets that control how your GEDCOM is processed. When you are satisfied with the options set you have selected, click on "OK" to initiate processing of your GEDCOM.

To preload an options set saved in a previous run of GED2HTML, enter the name of the saved options set in the "Options File" field, and then click on "Load". The previously saved options will be read in and used to initialize the various fields of the dialog box. To save the currently selected options, click on "Save". You will be prompted with a "Save As" box for selecting the name of the file to which to save the options set.

To make changes to the current options set, click on "Edit". This will bring up a second dialog box containing several more fields, entitled "Output Program", "Mail-to address", "Home page URL", and "Target Directory". These are used as described below. When you are satsfied with the options you have selected, click on "OK" to return to the top-level dialog box. Clicking on "Cancel" returns you to the top-level dialog box after abandoning any changes you have made.

The customizable fields appearing in the dialog box are listed and explained below. Note that there are many other options you can select that do not have their own fields in the dialog box. Those options are selected using the "Additional Options" field, as described here.

Output Program:

This field is used to enter the name of an output program to substitute for the built-in program. For more on output programming, see here.

Mail-to address:

If desired, enter your E-mail address in this field. GED2HTML will automatically place a "mailto" link at the bottom of the "top-level" persons and surnames index pages, to enable people viewing your pages to send you E-mail in a convenient way. It is highly recommended that you use this option, because I get lots of E-mail from people who are looking at GED2HTML pages created without "mailto" links, and who would like to contact the creator of the page with valuable additional information or corrections, but can't figure out how to do it.

Home page URL:

If desired, enter the URL of your main "Welcome" page here. GED2HTML will automatically place a "home" link at the bottom of each page of output, to enable people viewing your pages to navigate back to your home page. Use of this option is also highly recommended, because many people aren't familiar enough with the Web to figure out how to find a "home" page unless they have a specific link to it.

Target Directory:

By default, GED2HTML places its output in a subdirectory "HTML" of the directory from which it is launched. If you wish it to place its output somewhere else, put the name of that directory in this field. GED2HTML will attempt to create this directory if it doesn't already exist.

From the second-level dialog box, clicking on "More Options" will bring up yet another dialog box with lots of blanks and buttons. Below a brief description is given of each. After you are satisfied with the options you have selected, click on "OK" to return to the previous dialog box. Clicking on "CANCEL" returns you to the previous dialog box after abandoning any changes you made.

Individuals per file:

A number entered in this box determines the number of individuals GED2HTML will try to put in each of the individual data files it creates. Putting several individuals in a single file tends to save disk space on many systems. The default value is 10. To force GED2HTML to put exactly one individual per file, enter 0 in this field.

NOTE: If "Stable filenames" is selected (the default), then GED2HTML treats a positive value entered for "Individuals per file" as a suggested target value. It does not necessarily guarantee to put exactly the specified number of individuals in each file. If you must have exactly the specified number of individuals in each file, then turn off "Stable filenames". To understand more about how GED2HTML organizes information into various files, see here.

Files per directory:

A number entered in this box determines the number of individual data files GED2HTML will put in a single subdirectory. The default value is 100. If 0 is entered in this box, then GED2HTML will not use any subdirectories. Instead, it will create a "flat" structure in which all output files reside in the same directory.

CAUTION: Accessing directories with thousands of files in them is very slow under Windows, and especially under Windows 3.1. You are better off using subdirectories if at all possible.

Number of directories:

A number entered in this box forces GED2HTML to use a fixed number of subdirectories to contain the individual data files. The default value is 0, which permits GED2HTML to use as many directories as it sees fit. Note that a nonzero value entered in this box causes any value entered in "Individuals per file" to be ignored, and GED2HTML will put as many individuals as necessary in each file in order to output all the individuals using the specified number of directories and files per directory.

Sources per file:

For GEDCOMs containing many source records, putting all the sources in a single HTML file can produce a file that is too large to be downloaded conveniently over the Web. Entering a nonzero value in this field causes GED2HTML to output sources to multiple files, with the total number of sources output in any one file limited to the specified value. The default value is 0, which means put all sources in a single sources file.

Notes per file:

For GEDCOMs containing many notes records, putting all the notes in a single HTML file can produce a file that is too large to be downloaded conveniently over the Web. Entering a nonzero value in this field causes GED2HTML to output notes to multiple files, with the total number of notes output in any one file limited to the specified value. The default value is 0, which means put all notes in a single notes file.

Pedigree depth:

The value entered in this field controls the number of generations of ancestors that appear in the pedigree charts output in each individual data page. The default value is 2. Entering a value of 0 turns off the production of pedigree charts.

Indiv. index width:

The value entered in this field controls the maximum number of entries in each page of the hierarchical persons index. The default value is 28, which means that each index page will contain links either up to 28 individual data pages, or up to 28 "lower-level" index pages. In general, the more entries per page, the fewer "levels" of index are necessary to index a given number of individuals. Entering 0 in this field turns off the hierarchical index feature, causing a "flat" index to be created in which all individuals appear in a single index page.

Note that GED2HTML does not always put the maximum number of individuals in an index page. Rather, it tries to adjust the number of individuals in an index page to avoid producing lots of "widow" pages that contain very few entries. It generally succeeds at this, except that it is sometimes the case that the top-level index page has only two entries in it. If it occurs, this situation can generally be avoided by increasing the index width somewhat.

Surname index width:

For large GEDCOMs, putting all the surnames in a single surnames file can produce a file that is too large to download conveniently over the Web. Entering a nonzero value in this field causes GED2HTML to create a multiple-file surname index, in which the number of surnames in any given file is limited to the specified value. The default value is 0, which causes GED2HTML to put all the surnames in a single file.

Language:

The string entered in this field selects the (human) language that will be used to produce various components of the HTML output. For example, if "English" is entered in this field, or it is left blank, then the output will be in English. If, instead "French" is entered in this field, then the output will be in French. The currently available choices are "English", "French", "Danish", "Dutch", "German", "Italian", "Norwegian", "Swedish", "Finnish", "Slovenian", "Portuguese", and "Afrikaans".

For further information on the effect of changing the output language, see here.

Case fold links:

This group of three radio buttons selects certain processing to be performed on the URLs output in HTML anchors (hyper-links). If "Lower" is checked, then all URLs output by GED2HTML as part of HTML anchors are converted (folded) to lower case before being output. If "Upper" is checked, then all URLs are converted to upper case. If "None" is checked, then no conversion of any kind is performed. The default is "None".

The reason for this feature is to accomodate the ideosyncrasies of various systems and uploading software having to do what happens to MS-DOS-style upper-case-only filenames when the files are uploaded from a Windows system to a Web service provider's system. If your uploading software seems to create all files on the provider's system with lower-case names, then select "Lower", to make the hyper-links work properly once the files have been uploaded. If your uploading software creates all files on the provider's system with upper-case names, then select "Upper" instead. If you are using case-sensitive uploading software to upload from Windows to a Unix or Windows provider with a case-sensitive Web server, then "None" is probably the correct option to choose.

See here for additional discussion of the upper-case/lower-case issue.

Upper-case surnames:

Checking this box causes all surnames to be converted into upper case as the GEDCOM is read. The default is checked.

Output individuals:

Checking this box enables the creation of the data pages for individuals. The default is checked.

Output index:

Checking this box enables the creation of the persons and surnames indexes. The default is checked.

Output GENDEX:

Checking this box enables the creation of the "gendex.txt" index file, which can be used by index servers to centrally index your data so that others can find it more easily. The default is checked.

Omit sources:

Checking this box causes the program to completely ignore any source information present in the input GEDCOM. The default is unchecked. Note that this option is different than the "Produce sources" option that was present in previous versions of the program. The previous option could be used to suppress production of a separate sources file, but links to the missing sources would still appear in the data pages. The new "Omit sources" option causes the program to completely ignore source information right from the start, so that no sources appear in the output, and there are no dangling links.

Omit notes:

Checking this box causes the program to ignore any notes information present in the input GEDCOM (other than special notes used to flag living individuals, see here). The default is unchecked. Note that this option is different than the "Produce notes" option that was present in previous versions of the program. The previous option could be used to suppress production of a separate notes file, but links to the missing notes would still appear in the data pages. The new "Omit notes" option causes the program to completely ignore notes information right from the start, so that no notes appear in the output, and there are no dangling links.

CONT means break:

If this box is checked, then notes records in the GEDCOM that are continued over several GEDCOM lines using the CONT tag will be rendered in the HTML output with a line break <BR> before each CONT line. Continuation lines that use the CONC tag are rendered without a line break. This seems to correspond to the spirit of what the GEDCOM standard has to say about the use of CONT and CONC, however the output of some genealogy programs looks ugly this way. In such cases, unchecking this box makes CONT be rendered exactly like CONC; that is, without a line break. The default is checked.

Stable filenames:

Checking this box enables a feature that causes GED2HTML to use a "hash function" to calculate the directory and file in which the data for a given individual will appear, directly from the GEDCOM identifier for that individual. This has the advantage of making the mapping from individuals to directory/file pairs "stable" under additions to and deletions from the GEDCOM. This means that if you process your GEDCOM once, then add some new individuals to it and process your GEDCOM again, the second time all the individuals that were there the previous time end up in the exact same place in the output file as they did the first time. This feature can be advantageous for linking from external documents into the HTML tree output by GED2HTML. See here for more details. The default is to use this feature.

The disadvantages of checking "Stable filenames" are: (1) GED2HTML has less control over exactly how many individuals will end up in any given file; (2) the hash function randomizes the individuals so that a particular file will generally contain a number of completely unrelated individuals, rather than a group of individuals with the same surname.

The "Additional Options" Field

The other type of thing you can put in the "Additional Options" field are initializations for variables for the output interpreter. These initializations can be used to set existing options, or, in combination with modifications to the output program, to create new options. To cause the output interpreter variable "FOO" to be initialized with string value "BAR", you would put

Order of Options Processing

1. When GED2HTML.EXE starts, predefined default values are set for all the options.

2. Options settings are made by the user in the GED2HTML.EXE dialog box. These options can be saved by the user in a ".INI" file, and loaded back into the dialog box during a later run. Or, the ".INI" file can be edited directly if desired.

3. When the user clicks on "OK" in the GED2HTML.EXE dialog box to initiate GEDCOM processing, any options that were changed from the default values are output to the temporary file G2HOPTS.TMP. This file is used to communicate the changed options to the G2H.EXE program, which then starts.

4. G2H.EXE reads options settings from the file G2HOPTS.TMP.

5. G2H.EXE processes any settings the user might have made in the "Additional Options" field of the GED2HTML.EXE dialog box.

6. If an assignment has been made to the OUTPUT_PROGRAM option variable in any of the preceding steps, then the specified output program is located and compiled. Otherwise, the built-in standard output program is used.

7. G2H.EXE executes the procedure do_initialize in the output program. This function can be used to override options settings specified by the user using the dialog box.

8. G2H.EXE reads the GEDCOM file and produces output.

GED2HTML home page