Sentences

Sentence Overview

Gedcom Publisher creates text output using formatting instructions called "sentence templates".^{Note 1} Gedcom Publisher's sentence templates combine literal text and variable references, and the program substitutes text in place of the variable references to create text output. Some popular genealogy programs have similar features, and the formatting instructions are called "sentence structures", "sentences", etc.

Sentence templates are attached to events based on the type of the event and the role assigned to the person. The default role is "Principal" for the person (or persons) to whom the event applies. For GEDCOM files that include support for witnesses to events, also known as "shared events", the default role for a witness is "Witness". For GEDCOM files that include role information, Gedcom Publisher will assign the role defined for the person.

Source Application Sentence Support

Some applications include sentence templates in GEDCOM export files. Gedcom Publisher's support for those templates is summarized in the following table.

Global sentence templates are associated with a tag type (aka "fact" or "event"), and every tag of that type will use the default sentence unless the tag has a local sentence, i.e., a sentence associated with the specific tag, and often called a "customized" sentence.

• As of the last tested version, RootsMagic does not include local sentence templates for witnesses in its GEDCOM export file.
• For Family Historian, Gedcom Publisher only supports sentence templates when using Family Historian's "Export Gedcom File" plug-in. See the Family Historian page.
• For The Master Genealogist, Gedcom Publisher only supports sentence templates when using the "direct import" option. See The Master Genealogist page.
• Gedcom Publisher does not support sentence templates from applications except those listed above.

When Gedcom Publisher does not support sentence templates from an application, or if those sentence templates are not included, it uses sentence templates constructed following the rules described on the remainder of this help page. Gedcom Publisher includes pre-defined sentence templates for many tag types, but you may be using tag types outside that set. If so, you must define tag types in order to produce complete narrative output. Gedcom Publisher has a Default Sentence that you may choose to use when there is no sentence defined for a Tag Type.

Gedcom Publisher Sentence Templates

Gedcom Publisher includes sentence templates for many common tag types including Birth, Marriage, Death, etc. You may replace the sentence templates predefined by Gedcom Publisher using the Utilities > Edit Tag Types... command. You may also—and should—define sentence templates for any tag type where Gedcom Publisher does not provide sentence templates for you.

Here is an example of a simple sentence:

[S] died on [D] at [L]

• "[S]" is a variable reference. Gedcom Publisher will substitute the name of the subject in place of the [S]. See the variable list below.
• " died on " is literal text that will be included in the output.
• [D] is a variable reference. When formatting the text for an event, Gedcom Publisher will substitute the date of the event in place of the [D].
• " at " is literal text that will be included in the output.
• [L] is a variable reference. When formatting the text for an event, Gedcom Publisher will substitute the location of the event in place of the [L].

Some variables, such as [S] above, always produce text. Others, like [D] and [L], may or may not. For example, if no date is assigned to an event, the [D] variable will not insert any text into the output. In order to control the text around variables that may be empty, Gedcom Publisher supports variable expressions that combine literal text with variable references. The literal text is omitted unless the variable is not empty.

Here is an update of the previous example:

[S] died< on [D]>< at [L]>

• "< on [D]>" is a variable expression. If the event has a date, Gedcom Publisher will insert " on " and the date into the output. Otherwise, the expression produces no output.
• "< at [L]>" is a variable expression. If the event has a location, Gedcom Publisher will insert " at " and the location into the output. Otherwise, the expression produces no output.

As shown above, variable expressions may be used to add a preposition before a variable. For some variables, Gedcom Publisher supports automatic prepositions that vary based on the value of the variable. The automatic preposition is included when the variable expression does not include any literal text.

For dates, the automatic preposition varies as follows:

• The English preposition for a full date (day, month, and year) is " on ". Example: " on 6 December 1917".
• The English preposition for a month and year date is " in ". Example: " in December 1917".
• The English preposition for a year-only date is " in ". Example: " in 1917".

Here is an update of the example, now using the automatic preposition for the date variable:

[S] died<[D]>< at [L]>

It's possible to create flexible formatting instructions using variables and variable expressions as shown above. Gedcom Publisher also includes some additional capabilities to support highly customized output for events. Those capabilities are described below.

Variables and Variable Expressions

The core components of formatting instructions are variables and variable expressions.

Variables

The examples in Gedcom Publisher Sentence Templates above include simple variable references like [S] and [D]. Variables also support parameters that influence the output of the variable. The syntax of a variable reference is:

[variable:optional-parameter:optional-parameter ...]

A variable reference starts with [ and ends with ]. The text between the brackets must include a variable name, such as S or D. If a variable reference includes parameters, those parameters appear after a colon (":"). For example, to insert only the year from a date regardless of whether the date has a month and day or not, use the Y parameter of the D variable:

[D:Y]

Most variables output a value that comes from the GEDCOM data, such as the name of a person, a date, a location, etc. Some special-purpose variables produce a special value or influence the output in other ways. For example, the "+" and "-" variables are used in variable expressions to vary the output based on whether other variables are empty or not.

See the variable list below for more information about variables and variable parameters.

Variable Expressions

As shown in the Gedcom Publisher Sentence Templates section, variable expressions are used to vary text based on whether a variable has a value or not. They may also be used to evaluate alternatives and insert the first alternative that is not empty.

When a variable has a value, the variable is considered "true", and when a variable does not have a value, it is considered "false". Every variable reference produces a true or false result, and every variable expression also produces a true or false result. The true and false results influence the processing of the subsequent formatting instructions.

The simplest form of a variable expression refers to a single variable, for example:

<[D]>

The D variable reference returns the tag's date, if any. When wrapped in "<" and ">" to create a variable expression, the D variable reference will include the automatic preposition for a date, i.e., "on 12 May 1952", "in May 1952", or "in 1952".

You may include your own literal text before and/or after the variable reference:

<in [Y] or after>

The prefix "in " and the suffix " or after" will only be included in the output if the tag has a date with a year.

Variable expressions may include multiple variables. The variable expression will only produce output if all the variable references are not empty.

Alternatives

Variable expressions support alternatives where Gedcom Publisher will evaluate the alternatives until one of them produces output, i.e., until one has a "true" result. When an alternative produces output, the remaining alternatives are ignored. Alternatives are separated by the bar ("|") character:

< alternative1 | alternative2 | ... alternativeN >

A common use of alternatives is to vary the output based on whether an event has one or two principals:

[S] <and [PO] were|was> enumerated on the census< of [D:Y]>

The Gedcom Publisher variable expression alternative syntax looks similar to the "< | >" construct used in TMG, but there are important differences.^{Note 2}

Nesting

Variable expressions may be nested: one or more inner expressions may be an alternative for an outer expression. The Lifespan Example includes variable expression nesting.

Special Variables Used in Alternatives

Lifespan Example

Gedcom Publisher includes the parameter :LSP to produce a lifespan for a person. If you were attempting to produce similar output using Gedcom Publisher's variables and variable expressions, you could use the following sentence fragment:

<(<b. [S:PB]><[+:, ]d. [S:PD]>)>

For a person who was born in 1901 and died in 1977, the output would be "(b. 1901, d. 1977)".

Notes:

1. The formatting instructions will produce the correct output when there are no birth and death dates, only one or the other, or both.
2. "[S:PB]" produces the primary birth date of the subject. "[S:PD]" produces the primary death date of the subject.
3. Nesting is used to wrap the result in "(" and ")": if the inner expression is false, i.e., does not produce output, the outer expression will be false and the "(" and ")" will be suppressed.
4. The "<b. [S:PB]>" variable reference produces the "b. " prefix and the primary birth date if the person has a primary birth event and that event has a date.
5. The "[+:, ]" variable reference produces the ", " output, but only if the prior variable expression (the birth date) is not empty.
6. The "<[+:, ]d. [S:PD]>" variable expression has two variable references. As described in #5 above, the "[+:, ]" variable reference produces the ", " output if the prior birth date variable reference has produced output. "d. [S:PD]" produces the "d. " prefix and the primary death date if the person has a primary death event and that event has a date.
7. If the person does not have a primary death event, or if the primary death event does not have a date, the <[+:, ]d. [S:PD]> variable expression will not produce any output. The expression includes two variable references, and both must be true or the expression is false. The result of "[+:, ]" is always true, but it may or may not add text to the output. "[S:PD]" may or may not be true. If it is not, the variable expression is false and no output is produced.

Variable List

People Variables

Gedcom Publisher supports several variables to refer to people attached to an event. They are listed in this section. Each of those variables supports a common set of parameters to refer to characteristics of a person, such as the person's age. Those parameters are listed in the People Variable Parameters section. Absent any parameters, the variables produce the name (or names) of the people who match the description shown below.

Role Variable

The Role variable accepts a parameter that determines which roles to select. So, for example, "[R:Child]" will return a list of all people attached to the event with the role "Child".

You may specify more than one role by separating the role names with a comma, so "[R:Parent,Child]" will return a list of all people attached to the event with the role "Parent" or the role "Child".

You may specify any of the People Variable Parameters after the role name(s).

People Variable Parameters

People Variables accept parameters to choose which characteristic of a person you want to add to the output. The parameter is added after the variable name and a colon, for example, [S:A] produces the age of the subject.

People Variable Index

You may specify an index number with any person variable to access one of the qualifying people, from 1 to 9.

Examples

There are no standards for the sequence that witnesses are specified in a GEDCOM file, so the sequence number is not predictable and that limits its use. The most useful examples are [P1] and [P2].

N (Name) Parameters

Count Parameters

The people variables support "count" parameters you can use to vary the text based on the number of people who are included in the variable.

When a count parameter is used without any subsequent parameters, the variable reference returns true or false but does not produce any output. If you specify a parameter, the variable produces output if the number of people passes the count filter.

Count with No Parameters

The examples below use the W (witness) variable, but you may substitute any of the other People Variables including R:role, P, PO, A, AO, etc.

• [W:+] is true only if there is at least one witness
• [W:-] is true only if there are no witnesses
• [W:1] is true only if there is one witness only; works for [W:1] to [W:9]
• [W:1+] is true only if there is one or more witnesses; works for [W:1+] to [W:9+]
• [W:1-] is true only if there is one or fewer witnesses; works for [W:1-] to [W:9-]

Example:

<[R:Bridesmaid:2+]The bridesmaids were [R:Bridesmaid]|The bridesmaid was [R:Bridesmaid]>

Count with Parameters

The examples below use the W (witness) variable and the N (name) parameter, but the same structure works with other People Variables and Parameters.

• [W:1:N] will produce the name of the witness if there is one witness only; works for [W:1:N] to [W:9:N]
• [W:2+:N] will produce the name of the witnesses if there are two or more witnesses; works for [W:1+:N] to [W:9+:N]

Example:

<The bridesmaids were [R:Bridesmaid:2+:N:Given]|The bridesmaid was [R:Bridesmaid]>

Parent Parameters

The parent parameters (PARENTS, FATHER, MOTHER) support all the other person variable parameters. So, for example:

• [S:FATHER] returns the name of the subject's primary father
• [S:FATHER:A] returns the age of the subject's primary father at the time of the associated event, if the age can be calculated
• [S:MOTHER:PB] returns the date of the subject's primary mother's birth

Age Parameters

The A (age) parameter supports further parameters you can use to modify the value.

The A (age) parameter supports several further parameters to calculate a person's age without referencing an event. These are used internally by Gedcom Publisher to support predefined values for Person Fields in the List of People User Item. You may also use them in custom Gedcom Publisher sentence templates.

Living Age Warning

For several of the Age parameters above, Gedcom Publisher calculates the age of a living person based on the current date. For that reason, the value will be out-of-date as time passes after you make the book. This variable is mostly intended for books you create for auditing or analyzing your database.

ATTRIBUTE Parameter

The ATTRIBUTE parameter inserts the value of the named attribute into the output.

The ATTRIBUTE parameter supports an additional parameter you can use to test the attribute value. If the attribute value matches the parameter value, the variable reference returns true. Otherwise, it returns false.

Example:

[S] was <[S:ATTRIBUTE:Related_By:A]an ancestor|[S:ATTRIBUTE:Related_By:?]not related|related>

GENDER Parameter

With no additional parameters, the GENDER parameter inserts the person's gender into the output. The gender text is drawn from the Gender Strings properties.

The GENDER parameter supports an additional parameter you can use to test the gender value. When any of these parameters are used, the variable reference returns true or false but does not produce any output.

• [S:GENDER:F] is true only if the subject is female.
• [S:GENDER:M] is true only if the subject is male.
• [S:GENDER:U] is true only if the subject's gender is unknown.

The "GENDER:F", "GENDER:M", and "GENDER:U" parameters are not subject to translation in response to the site language, so you should always use the English values shown here.

Example:

[S] was <[S:GENDER:F]female|[S:GENDER:M]male|an unknown gender>

Primary Image Parameters

The Primary Image parameter for a person variable accepts the following parameters. All the parameters are optional, but they must be specified in the sequence shown in the table. For example, to supply the third parameter (alignment), you must specify width and height.

[S:PI:width:height:alignment:class:lightbox:caption]

To insert an image that is a maximum of 200 pixels wide by 250 pixels high, with left-alignment, no user class, no lightbox functionality, and with a caption, specify the parameters as follows: [S:PI:200:250:left::N:Y]

Tag Variables

The Tag Variable [T] supports several parameters to refer to name and event fields. For convenience, some of those parameters may be used without specifying the "T:" prefix. With the "T:" prefix or with no prefix, the references refer to properties of the current tag.

[S] was born<[T:D]>

[S] was born<[D]>

You may use Tag Variable parameters with the PB and PD parameters of People Variables.

The father of [S] was born< in [S:FATHER:PB:L]>

Tag Label Parameters

The T:TL or TL variables supports the following parameters.

M (memo) Parameters

The M (memo) parameter returns text associated with the tag. It supports a part name as a parameter and/or several keyword parameters.

Part Name Parameter for M Parameter

For GEDCOM tags that Gedcom Publisher treats as Events, there may be one or more text properties. Gedcom Publisher stores the text properties under a part name that indicates the origin of the text in the GEDCOM file and/or the meaning of the text. You may insert one or more of those text properties using the M (memo) parameter.

The two most common parts are "Text" and "Note". There are other part names that are specific to certain GEDCOM tags.

The "Text" part contains any text that is on the main GEDCOM tag for the event. For example, the GEDCOM NCHI tag is used to record the number of children for a couple. The family record for a couple with five children would include an NCHI tag as follows:

1 NCHI 5

When Gedcom Publisher reads the GEDCOM file, it puts the "5" text into the "Text" part of the memo.

The "Note" part contains any text that is recorded via a GEDCOM NOTE tag. Expanding on the example above, the GEDCOM NCHI tag may include a child NOTE tag to include additional text. The family record for a couple with five children might include an NCHI tag with a NOTE tag as follows:

1 NCHI 5
2 NOTE All children were born in Maine

When Gedcom Publisher reads the GEDCOM file, it puts the "All children were born in Maine" text into the "Note" part of the memo.

Part Name Examples

Keyword Parameters for M Parameter

The M (memo) parameter supports these keyword parameters:

A (article) Parameter for M Parameter

The M (memo) parameter supports an A parameter that you may specify prior to any part names. The A (article) parameter will insert "a" or "an" before the part text. This is useful when constructing the sentence for an Occupation event, for example:

[S] was [M:A:Text]<[L]><[D]>

If the Text part is "farmer", the output will be:

John Smith was a farmer.

If the Text part is "accountant", the output will be:

John Smith was an accountant.

At present, the A parameter will only return a value for English (U.S.) and English (UK). Future versions may add support for other languages.

Split Text

Some genealogy programs support split text fields where the text is divided into sections using special characters. For example, TMG uses the "||" characters to split text:

memo part 1 || memo part 2

Gedcom Publisher recognizes TMG's split text delimiters and divides the text into separate parts. Gedcom Publisher appends the sequential part number to the base part name to produce the names of the second and subsequent parts.

Split Text Example

Given the following records in a GEDCOM record written by TMG:

1 BIRT
2 NOTE 9 pounds 6 ounces || 20.5 inches

The note for the Birth event would be split into two parts accessible through the following sentence variables:

D (date) Parameters

The D parameter supports the following additional parameters.

L (location/place) Parameters

Gedcom Publisher supports multiple place records for a single event. The GEDCOM converter assigns an index number based on the intended use of the place record. The PLAC record, if any, is assigned to index 1. The ADDR record, if any, is assigned to index 2. Some source applications have custom GEDCOM tags for additional place records, and those are assigned index 3 or higher.

By default, the L parameter will return data from the place record with index 1. To access a different place record, specify the index number using the :I parameter, i.e., :I2, :I3, etc.

The L parameter supports the following additional parameters.

Place Prefix

The L parameter supports several prefix options described above. They were implemented primarily to support source programs that specify a prefix via an option on a variable name. In a Gedcom Publisher sentence, it's typically best to let Gedcom Publisher determine the prefix, or add a prefix with an expression, i.e., "<in [L]>".

Place Parts

The L parameter supports named place parts and will restrict the output to those parts only. Unfortunately, standard GEDCOM does not support named place parts, and most GEDCOM source programs do not provide the information via custom GEDCOM tags. Gedcom Publisher stores the text on the GEDCOM PLAC record in a part named "@Full".

Variables for Formatting

The following variables are used for formatting text.

HTML Expressions

Gedcom Publisher's variable expressions use the "<" and ">" characters that are used in HTML to start and end HTML tags. As a result, if you want to use HTML in a Gedcom Publisher sentence, you usually must escape the "<" and ">" characters using Gedcom Publisher's escape character, "\". So, "<" and ">" are entered as "\<" and "\>" when adding HTML to a sentence.

For convenience, Gedcom Publisher recognizes several HTML tags even when the "<" and ">" characters are not escaped. It treats them as "HTML expressions". To use the following small subset of HTML, you can enter the text without escaping the "<" and ">" characters.

Seams and Punctuation

As Gedcom Publisher evaluates a sentence, it appends new text to the end of any previous text in the output until there are no more variables or literals to process. The text location where new text is added to the existing text is called a "seam".

Gedcom Publisher adjusts punctuation at seams. If the characters on either side of the seam are punctuation, Gedcom Publisher chooses one or the other, but doesn't leave both. The rules vary based on the characters involved. Gedcom Publisher ignores spaces when it evaluates whether either side of the seam is a punctuation character.

The Sentence Strings section defines the characters that are considered punctuation so that Gedcom Publisher can be configured to support different languages.