The Lancashireman's software

Red rose of Lancashire


DhG is a suite of programs, libraries and other odds-and-ends that I use for maintaining a database of people as part of my family history research. I'm making it available to download free-of-charge on the off-chance that someone else might find it useful too.

DhG is a command-line program that has been designed to work on unix-like operating systems such as GNU/Linux and FreeBSD. It might be possible to run it on a Mac (OS X) because that's BSD-based too. It might also be possible to run it on Windows; I haven't tried.

DhG is written in perl and therefore needs a standard perl interpreter. It also depends on the Template toolkit, which is available as an optional extra on some GNU/Linux distros. On Ubuntu the package is called "libtemplate-perl".


You can get the latest version of DhG here.


Create an empty directory somewhere in your file system. Download the DhG tarball from the link above and plonk it into the empty directory.

Open an xterm or some other Terminal window, cd to the directory you created and unpack the DhG tarball. You can delete the tarball now:

        cd /whereever/you/put/DhG
        tar xzvf DhG.tar.gz
        rm DhG.tar.gz

If the directory /usr/local/lib/site_perl already exists, go to the next step. Create the directory /usr/local/lib/site_perl --- you'll need root permissions, so:

        sudo mkdir /usr/local/lib/site_perl

Create symbolic links in /usr/local/lib/site_perl for all the perl-module files in the DhG suite:

        sudo ln -s `pwd`/*.pm /usr/local/lib/site_perl
There are other places you can put the modules if you don't have root permissions or if you don't want to modify /usr/local/lib/site_perl. One way is to put the path to the modules into the environment variable PERL5LIB.

Edit the file DhG. It's a shell script, and you need to configure the directories:
/path/to is the directory where you unpacked the DhG tarball.
===WORKING-DIRECTORY=== is a working directory. This is where DhG puts all the generated output.
===DATABASE-DIRECTORY=== is the database directory. DhG scans this directory and all its subditrectories for files with the .card suffix.
As an example, here's my script:

        cd /data/family-history/DhG-dir
        exec /data/family-history/tools/DhG/ /data/family-history/database
You can do other useful things in this script. This is one possible place to set the PERL5LIB environment variable. You can also select your editor; DhG uses the vi editor by default, which isn't to everyone's taste. You can select your editor the old-fashioned way by setting one of the environment variables VISUAL or EDITOR. DhG first looks as VISUAL then at EDITOR. So
        export VISUAL
in the script (before the 'exec' line) tells DhG to use gedit. IMPORTANT: Always use a text editor for this job. Never use a word processor. One thing to note: DhG always suspends itself while the editor is running. When the editor runs in the xterm this is what you'd expect, but with a GUI editor like gedit, you can minimise the editor window and then it looks like DhG has crashed. The hint here is the last line of output from DhG: if it says something like
        Editing /data/family-history/database/Bloggs/FredBloggs-99.card...
then the editor is still running, so find it, save the file and close the editor (or quit without saving - whatever is appropriate).

Finally, copy the DhG script to somewhere in your $PATH (~/bin is usually a good place).


Make your xterm big enough. I use 120x75 characters. Type DhG at the prompt. You should see something like:

help                     = Print this text
list                     = List all people
family <person>          = Print family of a single person
descendants <person>     = Print all descendants of a single person
ancestors <person>       = Print all ancestors of a single person
search <pattern>         = Print name of people that match given terms
find <pattern>           = Print name of people that match given terms
quit                     = Close program
edit <person>            = Edit a person's card
vi                       = (alias for edit)
reload                   = Reload the database
set <name>=<value>       = Set a variable
htmlcard <person>        = Output a card file in HTML
htmlcard all             = Output a card file in HTML for every person in the database
htmlcard public          = Output a card file in HTML for every "public" person in the database
hc                       = (alias for htmlcard)
htmldesc <person>        = Output a public descendant tree in HTML
htmldesc @<filename>     = Output a public descendant tree in HTML for each person listed in the file
hd                       = (alias for htmldesc)
htmlprivdesc <person>    = Output a private descendant tree in HTML
htmlprivdesc @<filename> = Output a private descendant tree in HTML for each person listed in the file
hpd                      = (alias for htmlprivdesc)
htmlanc                  = Output an ancestor tree (Ahnentafel) in HTML
ha                       = (alias for htmlanc)

(c) 2014  David Haworth (;
DhG comes with ABSOLUTELY NO WARRANTY. It is free software, and you are welcome
to redistribute it under certain conditions; please read the accompanying file
gpl-3.0.txt for details.

What now?
Have fun! Try creating your first person:
        new Fred Bloggs

There's a bit more detail in the user's manual.

Problems, bugs etc.

If you run into problems or find a bug, send me an email using the address on the about page.

© David Haworth
About this site (Impressum).
Don't say Greater Manchester, Merseyside or Cumbria when you mean Lancashire Valid XHTML 1.1 Valid CSS!