Customizing GED2HTML with Output Templates

One of the features of GED2HTML is that output processing is completely controlled by user-specifiable programs, called ``templates.'' Templates are written in a truly awful programming language I designed specifically for this purpose. To tell the truth, it was designed more for ease of interpretation than for ease of programming, and it shows. 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 templates (the defaults used in the Un*x version of the program) 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'', ``-t'', and ``-R'' 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 specify a `-' instead of the name of a template file, for example: ged2html -t - the program will output the compiled-in default version of that template file on the standard 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.'' Even I only modify the templates with a debugger close at hand. 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'' (in the Un*x distribution) 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.

If you are really convinced that you want to make your own templates, first 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 object'' (individual, index, or source).
[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. Conditional execution uses the following control constructs:

!IF condition
!THEN
!ELSE
!ENDIF

These provide for conditional output based on whether particular fields in the database have non-null values. Looping constructs are the following:

!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.

The construction:

!RESET index_variable

resets the value of an index variable to 1. The construction:

!INCREMENT index_variable

increments the value of an index variable. The construction:

!NEXT

advances "@" to refer to the "next" individual, index, or source in the database.

External HTML code can be inserted inline using the following construct:

!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.

The construct:

!PEDIGREE indiv_variable

causes a ``pedigree chart'' of the default depth (specifiable by a command-line option, see here) 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.

The construct:

!DATE

inserts the current date into the HTML output. The construct

!VERSION

inserts the version number of GED2HTML into the HTML output.

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!

Please note that I have not made any specific attempt to support ``locales'' or international character sets. Except for converting surnames to upper-case (which can be disabled with a command-line option, see here), the program generally does not mutate input characters supplied to it, and I have at least seen German characters with umlauts, etc. passed properly by the program. I have also had feedback from someone who used an older version of the program to process Hebrew. It apparently worked for the most part, though there were a few problems that may have been caused by the program trying to capitalize surnames.

GED2HTML home page