The Lancashireman's software

Red rose of Lancashire

DhG User's Guide

Quick start

Run the program, use the new command to create files for all the people in your family tree, use the reload command to make sure the information has been loaded, then create family trees using the ancestor and descendant commands. Easy peasy :-)

But seriously ...

Principle of operation

DhG uses structured text files to store information about individuals in your family tree. These files are called "cards" and have the suffix ".card" - a bit like electronic versions of cards in a card index. Each card contains information about a single person. The information that is stored can be as little or as much as you like, but for the family analysis to work each person's father and mother are needed wherever possible. Other information such as birth, baptism, marriage, death, burial and census records can be stored. Parent to child relationships are not stored in the parents' cards but are inferred from the children's cards.

DhG does not store this information itself; rather, it directs you to create the cards using a normal text editor. Apart from the step of initially creating a person's card, DhG does not modify any of the cards. It simply uses the information in the cards to construct relationships and produce various reports in plain text and HTML format. This method of operation means that you can safely close DhG at any time without losing any data. It also means that several instances of DhG can be running on the same database at the same time, but if you do this you need to take care when editing cards and especially when creating new ones; there is a danger that the same unique number will be allocated to two different people.

Command-driven operation

DhG, or more precisely its browser program Dh_GBrowse, runs in a terminal window and uses a command interface. At the "What now?" prompt you type in a command and Dh_GBrowse does what the command tells it to do.

Dh_GBrowse uses the readline library to accept commands. This means that you can recall commands from the list you have already typed using the up-arrow and down-arrow keys. You can edit commands by using the left-arrow and right-arrow keys to move the cursor, insert new characters by typing them and delete characters by using DEL or BACKSPACE. Filename completion is available by pressing TAB, but this is of limited use because Dh_GBrowse's use of files and directories is mostly hidden.

The commands you type can be abbreviated to the first few characters, but you must type enough characters for the command to be unambiguous.

Structure of a card

The following example illustrates how a card should be written. The exact layout is not very important - the number of spaces, for example, can be chosen to make the cards easy to read. What is important is the line structure and the grouping of lines. The order of events in the card is used when an HTML card for the person is produced, otherwise it plays no role in the analysis.


Name:       Fred Bloggs
Uniq:       222
Male
Father:     Joe Bloggs [123]
Mother:     Ada McTiggle [136]
Version:    2


1827-04-22  Birth
+Source     Baptism record

1827-05-01  Baptism
+Place      St Never, Much Binding in the Marsh
+Source     Baptism certificate
-File       Image       BAP-1827-FredBloggs.png
+Source     Genealogic
-URL        http://genealogic.org/parishes/StNeverMuchBinding.html#1283
-Transcript
| 1827 1st May  Fred son of Joe and Ada Bloggs  Born 22nd April   Rev. Tarquin Fintimlimbim

1853-04-23  Marriage    Ethel Gumby [247]
+Place      St Away, Little Binding
+Age        26
+Source     Marriage certificate
-File       Image       MC-1853-FredBloggs-EthelGumby.jpeg

1877-09-17  Death
+Abode      Rose Cottage, Much Binding
+Age        50
+Source     Death certificate
-File       Image       DC-1877-FredBloggs.png
+Source     Gravestone (see Burial)

1877-09-20  Burial
+Place      Grave 412, St Never Churchyard, Much Binding
+Source     Gravestone
-File       Photo       Gravestone-StNever-Bloggs-1.jpeg
    

This is a fairly simple card file, but contains all the necessary elements for DhG to analyse Fred's relationships and place him into the family tree. Let's look at the individual lines in this file one at a time...


      Name:       Fred Bloggs
This is the person's name. Everybody has one, so it has to be present. In some cases you might only know part of the name. For example, the mother's maiden name might not be known, or the forename of a child might not be known if you're gathering information from relatives. In these cases it's useful to use a placeholder such as "unknown". I frequently use "_". It may also be useful to create a card file for someone for whom no name is known. This happens in older baptism records when only the father's name was given - but you know that a mother must have existed.

      Uniq:       222
This is the unique identifier that is assigned to the person. Every person must have an identifier, and the identifier must be a positive number. Don't use 0. Dh_GBrowse automatically assigns a unique identifier when you use the "new" command.

      Male
The person's gender. "Female" is also valid. Dh_GBrowse doesn't use this for any practical purpose at the moment, although it might be of use for future features. When Dh_GBrowse starts (or when the "reload" command is used), it notes the relationship between first name and gender, so that (given a large enough database) the gender of a new person can be guessed. A message like "Rennie could be a M or F name" at startup simply means that there are several people called Rennie in the database; some male and some female.

      Father:     Joe Bloggs [123]
This indicates who Fred's father was. The name makes the card file nicely readable and the unique identifier (in brackets) guarantees that Dh_GBrowse finds the correct person when analysing the relationships.

      Mother:     Ada McTiggle [136]
This indicates who Fred's mother was. McTiggle was her maiden name.

      Version:    2
This indicates that the card uses version 2 of the card layout specification. If this line is omitted, nothing bad will happen because DhG only supports version 2 now. However, it's a good idea to leave it in place in case the structure changes again.

      1827-04-22  Birth
This line is the start of a "Birth" event. It gives the date of birth. DhG uses the date in the reports. DhG treats any line that starts with a numeric digit or '?' as the start of an event; the first field (up to the first space) is the date of the event. The complete set of date formats is described later. For all types of event, the following lines of text provide extra information about the event. The lines starting with a '+' symbol are primary information. Lines starting with a '-' symbol are secondary information - these are usually file names, URLs etc. relating to +Source lines. Lines starting with '|' are continuation lines and are usually used with a -Transcript line. following lines that start with '+', '-' or '|' provide extra information about this event.

      +Source     Baptism record
This line indicates the source of the information about the date of birth. In this case, the date comes from the baptism record, which is recorded below the birth record.

      1827-05-01  Baptism
The start of another event; in this case, Fred's baptism.

      +Place      St Never, Much Binding in the Marsh
A primary information line providing more information about the event. In this case, where the event took place.

      +Source     Baptism certificate
The source of information is Fred's baptism certificate.

      -File       Image       BAP-1827-FredBloggs.png
A secondary information line; in this case indicating that the source (the baptism certificate) can be found in a file called BAP-1827-FredBloggs.png. I don't put the full path name to files into the cards; it gives me the freedom to rearrange my computer without having to edit all my cards. Searching for files is a routine job for computers, and to speed things up there are various indexing programs available.

      +Source     Genealogic
Another source; in this case a fictitious website called Genealogic that purportedly provides parish records.

      -URL        http://genealogic.org/parishes/StNeverMuchBinding.html#1283
Another example of a secondary information line. In this case, it's the URL of the transcript. Be wary of pay-to-view sites here; if you use the HTML features of DhG to create a website, your visitors might not be able to see the record. Even worse - they might get charged unexpectedly!

      -Transcript
      | 1827 1st May  -  Fred son of Joe and Ada Bloggs  -  Born 22nd April  -   Rev. Tarquin Featherstonehaugh
Another secondary information line about the Genealogic source. It's a transcript of the record. Note the continuation line starting with '|'.

      1853-04-23  Marriage    Ethel Gumby [247]
Another event, in this case Fred's marriage. Note that the spouse is named on the same line.

      +Place      St Away, Little Binding
      +Age        26
      +Source     Marriage certificate
      -File       Image       MC-1853-FredBloggs-EthelGumby.jpeg
Further information about the marriage, presumably extracted from the marriage certificate.

      1877-09-17  Death
Fred's death

      +Abode      Rose Cottage, Much Binding
      +Age        50
      +Source     Death certificate
      -File       Image       DC-1877-FredBloggs.png
Further information about Fred's death, extracted from the source.

      1877-09-20  Burial
      +Place      Grave 412, St Never Churchyard, Much Binding
      +Source     Gravestone
      -File       Photo       Gravestone-StNever-Bloggs-1.jpeg
Fred's burial in the churchyard.

As you can see, the card structure is quite straightforward. For most of its functions, DhG only uses the name, the unique number, the father and mother and the birth, marriage and death events. The other information is used when creating HTML versions of the index cards for use on a website.

The event types and the keywords for primary and secondary information lines are flexible; you can add your own custom types if you like. DhG only uses the first word of the event type and the rest of the line is ignored. There are two exceptions to this behaviour; the Marriage event identifies the spouse, and there is an event type called "Misc", where the rest of the line is used as a description of the event.

The standard event types and information keywords are shown in the keywords section.

List of commands

help
Print a list of commands and a brief description for each.
list
List all people in the database.
family <person>
Print the immediate 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 names of people that match given terms.
find <pattern>
Print names of people that match given terms.
quit
Close the 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.

A person is specified either by name or by unique identifier. If a name is given DhG uses a search algorithm rather than an exact match, so you can just type in some parts of the name, such as "Fre Bl" if you want Fred Bloggs. If there's more than one match, DhG prints a list of matches instead of performing the command. You can then repeat the command using a better match; alternatively (and more likely) you can use the unique identifier.

The pattern for the search and find commands works just like the name variant for specifying a person.

A "private" person is one who is still alive (i.e. for whom no death is recorded), or who has been explicitly marked as private using "Private" on a line by itself in the card (usually in the header near the name. In any given family, a whole generation will be treated as private if any one of them or their spouses, siblings, siblings of spouses, spouses of siblings etc. is alive of marked as private.

The set command is used to set internal variables. The variables that are recognised are DBG, FORMAT, DATE and CARDBASE.

DBG
The "debug" level (a number from 0 upwards), which controls how much diagnostic information is printed. Leave at the default of 0 for normal operation.
FORMAT
No longer used.
DATE
Controls the format of the date when printing or generating HTML output. Possible values are raw, yearonly, noquarter.
CARDBASE
Specifies the directory where new card files will be created. New files will be created in a subdirectory of this directory by the surname. E.g. Fred Bloggs' card file would be called $CARDBASE/Bloggs/FredBloggs-222.card. By using CARDBASE, you can separate the major branches of your tree into different directories.

List of keywords

The following is a list of the keywords that I use in my files. DhG only attaches a special meaning to a small subset of these keywords and the rest are just used as labels. However, if you use the same keywords that I use, then your database will be compatible with future features.

Header keywords

Header keywords are used either alone on a line or followed by a colon and a value.

Name
The name of the person in this card file. The name is a set of strings separated by spaces. The first one is considered to be the forename, the last one the surname. A double-barrelled surname like Ponsomby-Smythe should work but I haven't tested it because I haven't found one in my tree yet.
Uniq
The numerical unique identifier of the person in the card file. This must be a number from 1 upwards and must be unique in the entire database.
Version
The version of the card file structure. Should be 2 if used.
Male
The gender of the person in the card file. Used alone (no value).
Female
The gender of the person in the card file. Used alone (no value).
Public
Indicates that this is a "public" person. I'm not sure this is used at the moment. Used alone (no value).
Private
Forces a dead person to be treated as private. Used alone (no value).
Father
Names the father of the person in the card file. The name should be specified in full including the unique identifier.
Mother
Names the mother of the person in the card file. The name should be specified in full including the unique identifier.

Event keywords

Events are specified by a line containing a date, an event keyword and (for some event types) some extra information.

Birth
The birth of the person in this card file. No extra information. The date of the event is used by DhG.
Baptism
The baptism of the person in this card file. No extra information.
Marriage
A marriage of the person in this card file. The spouse is specified in the extra information. This information is used when constructing family trees and is especially useful for childless marriages.
Death
The death of the person in this card file.. No extra information. The date of the event is used by DhG.
Burial
The burial of the person in this card file. No extra information.
Census
A census record for the person in this card file. No extra information.
Misc
An event in the person's life. The extra information in this event type is used as the event type when creating an HTML card file for the person. This is how to get multiplle words like "Military service" into the HTML timeline.

Primary information keywords

After an event, lines starting with a '+' character are treated as primary information for the event, such as place, age etc. The lines are intended to contain information that is extracted from records of the event and is only as accurate as those records.

Most of these keywords are not interpreted in any special way by DhG, so these are just examples.

Place
Where the event took place.
Abode
Where the person was living at the time of the event.
Age
The age of the person at the time of the event.
After
The earliest possible date for the event.
Before
The latest possible date for the event.
Birthplace
The place of birth of the person.
Until
For events with a duration (e.g. military service): the end date of the event.
Todo
A reminder that the information isn't complete :-).
Informant
The informant (e.g. from a death certificate).
Witness
A witness (e.g. from a marriage certificate).
Occupation
The person's occupation at the time of the event.
Theory
A remark by the database editor indicating what might be the reason for strange-looking information.
Source
A source for the information about the event. Source lines are used by DhG when constructing HTML cards and are placed in a specal column. If a secondary URL line is present (see below), the source name is converted to a link.

Secondary information keywords

After a primary information keyword there can be secondary information keywords. At the moment, these only apply to the Source lines, and are used to indicate where the source material can be found. As usual, they are flexible. Very few are actually interpreted by DhG.

File
A file on the local PC containing an image or transcript of the record. The file name is preceded by the type (Transcript, Image, Photo etc.) and is specified without directory path.
Page
If the source is a whole document, this specifies the page number.
From
For second-hand information, this indicates who the source was..
URL
A URL for the record. When generating an HTML card, DhG uses this URL to convert the source text into a link.
Transcript
A transcript of the source record. The transcript can go over several lines using the continutaion character '|'. I recommend putting the entire transcript on continuation lines for readability.

Annoying "features"

After creating or editing a card, the new information isn't in the database until you reload.

The CARDBASE variable has no default value; you are forced to set it before you can create a new card.

DhG tries to be as flexible as possible when reading the card files, so incorrect keywords are often ignored with no error messages.


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