Fact Types Dialog

Sentence Template Codes

Sentence template codes are mainly used to define sentences for narrative reports. There are two kinds of sentences: Principal sentences and Witness sentences. Principal sentences define a fact from the point-of-view of the principal (or from the point of view of one of them if there are two). Witness sentences describe a fact from the point-of-view of a witness. A Witness can be defined more than once, with more than one role, for any given fact - in which case they will get a Witness sentence for each role, in any narrative report about the Witness. A Principal isn't usually defined as a Witness in their own fact, but they can be if required. Even if they are, however, they will nevertheless only get one sentence for the fact, in any narrative report about the Principal - and this will be a Principal sentence.

Most sentence template codes can be used in either Principal sentences or Witness sentences - but not all. Where a code can only be used in one context, this will be mentioned in the code description.

To learn more about sentences (and witnesses, principals and roles), see the help for the Witnesses Window, which also explains how to override sentences. This can be a good way of testing your sentence templates to make sure that they deliver the results you were expecting. To clear an overridden sentence, click on the button to the right of the Sentence field and click on Reset Sentence from the dropdown menu that appears.

Simple sentences can be defined using standard codes. However, if you have more complex requirements, you can also use data references or even functions in sentence templates (see How to Add Data References or Functions to Sentence Templates below).

Comparison with Source Templates

Sentence templates are similar to source templates (used in reports, to specify the formatting of source citations). Although there are many points of similarity, there are also important differences and you are advised to be careful not to confuse the two, and to treat them as separate and distinct. In general, the expressions you can use to construct source template formats, are more flexible and powerful than the expressions that can be used within sentence templates. For more on source templates, see Source Template Formats.

Standard Data Codes

Code: {individual}

Will be replaced by the name of the individual or 'he' or 'she', depending on the context.

Name of Individual (or Him/Her)

Code: {individual/him/her}

Will be replaced by the name of the individual or 'him' or 'her', depending on the context.

Name of Individual (or His/Her)

Code: {individual's}

Will be replaced by the name of the individual or 'his' or 'her', depending on the context.

Him/Her

Code: {him/her}

Will be replaced by 'him' or 'her', depending on the sex of the individual.

His/Her

Code: {his/her}

Will be replaced by 'his' or 'her', depending on the sex of the individual.

Principal

Code: {principal}

Witness sentences only. Used with individual facts. Will be replaced by the name of the fact-owner. For example, if the fact is baptism, it will be replaced by the name of the person being baptised.

Principal(s)

Code: {principals}

Witness sentences only. Used with family facts. Will be replaced by the name of the fact-owners. For example, if the fact is marriage, it will be replaced by the name of the two people being married.

Name of Spouse (or Her/Him)

Code: {spouse/her/him}

Principal sentences only. Used with family facts. Will be replaced by the name of the individual's spouse or 'her' or 'him', depending on the context.

Names of Couple (or They)

Code: {couple}

Principal sentences only. Used with family facts. Will be replaced by the names of the two participants in a family fact (e.g. marriage), or by 'they', depending on the context.

Date

Code: {date}

Will insert the date in a text format, with an appropriate prefix. For example, if the date is an exact day, the prefix will be 'on' (e.g. on "30th January, 2001"). If the date is a month or year, the prefix will be 'in' (e.g. in 1998). If the date is a range or a period, again appropriate prefixes will be used.

The date code can be qualified to specify a particular date format. See Advanced Features of Sentence Template Codes below.

Age

Code: {age}

Used with Individual facts only. Inserts details of the person's age at the time of the event, if recorded.

Age Range

Code: {age range}

Used with Individual facts only. Inserts details of the person's age at the time of the event, if recorded. If no age information has been recorded, the person's possible age range will be calculated from their date of birth, and the fact date, if these have been supplied.

Their Ages

Code: {their ages}

Principal sentences only. Used with Family facts only. Inserts details of the ages of the parents in a family record at the time of the event, if recorded.

Their Age Ranges

Code: {their age ranges}

Principal sentences only. Used with Family facts only. Inserts details of the ages of the parents in a family record, at the time of the event, if recorded. If no age has been recorded for either parent, that person's possible age range will be calculated from their date of birth, and the fact date, if these have been supplied.

Place (with prefix 'in')

Code: {place}

Inserts the place name (usually in the 'Tidy' format where repeated commas are reduced to a single comma), with the prefix 'in'.

Tip: In narrative reports you can opt to only use the first part of a place name when replacing template codes for places, if that particular place has already been mentioned in full earlier in the same section. This avoids unnecessary repetition of information and is enabled by default. See the Use Short Form for Repeated Place Names option in the Main tab of the Options dialog for the narrative report in question.

Place (with no prefix)

Code: {_place}

Inserts the place name (usually in the 'Tidy' format where repeated commas are reduced to a single comma), with no prefix. If you want a prefix, but just don't want 'in', see How to Add a Prefix or Suffix to Any Sentence Template Code below.

Secondary Place

Code: {_place2}

Used with immigration and emigration events only as each of these, unlike all other fact types, are associated with 2 places: the place the person immigrated to and the place they emigrated from. This code causes the secondary place to be inserted.

Cause

Code: {cause}

Inserts the cause, if any, associated with the relevant fact.

Address

Code: {address}

Inserts the address, if any, associated with the relevant fact.

Tip: see How to Add a Prefix or Suffix to Any Sentence Template Code below, for suggestions about how to add a prefix to an address.

Note

Code: {note}

Inserts the note, if any, associated with the relevant fact.

Fact Label (e.g. 'Occupation')

Code: {label}

Inserts the fact label (e.g. 'Occupation').

Fact Value (e.g. 'Accountant')

Code: {value}

Only used with attributes. Inserts the fact value.

Fact Value (with a/an prefix)

Code: {a/an value}

Only used with attributes. Inserts the fact value prefixed by 'a' if the value begins with a consonant (e.g. 'a sailor') or by 'an' if the value begins with a vowel (e.g. 'an airman').

Abbreviation

Code: {abbr}

Will be replaced by the fact abbreviation if there is one, or the fact label if there isn't.

'Child' or 'Children'

Code: {'children'}

Used with the Child Count field only. Is replaced by the word 'child' if the person had 1 child only. Otherwise it is replaced by the word 'children'.

'Spouse' or 'Spouses'

Code: {'spouses'}

Used with the Marriage Count field only. Is replaced by the word 'spouse' if the person had 1 spouse only. Otherwise it is replaced by the word 'spouses'.

Blank

Code: {blank}

Use this code on its own if you don't want a sentence to appear.

Role Codes

Role codes are a special kind of data code, used with witness information.

Role Name

Code: {role name}

Witness sentences only. Will be replaced by the current witness's role in the current fact (e.g. the word 'bridesmaid' if that was their role).

Role Holders

Code: {role=____}

The blank must be filled by one or more role names or the words 'principal' or 'principals'. Multiple values are allowed and must be separated by a comma. For example, {role=bridesmaid} will be replaced by a comma-separated list of all witnesses that have the role 'bridesmaid'. The expression {role=bridesmaid,best man,principal} will return a list of everyone who is either a witness with the role 'bridesmaid', a witness with the role 'best man', or a principal, for the fact in question. If a person qualifies to be in the list more than once, they will only be listed once. This code may be used in both principal and witness sentences. In practice, it will almost always be 'wrapped' within angle brackets like this: "<The bridesmaids were {role=bridesmaid}.>" (see How to Add a Prefix or Suffix to any Sentence Template Code below).

The 'role' code can be qualified to specify a particular name format. See Advanced Features of Sentence Template Codes below.

Role Holder (if singular)

Code: {role(single)=____}

This code behaves exactly like the code {role=____} above, except that if more than one person qualifies to be in the list, it will return nothing. This means that an expression such as "<the bridesmaid was {role(single)=bridesmaid}>" will be blank in its entirety, if there is more than one bridesmaid.

The 'role(single)' code can be qualified to specify a particular name format. See Advanced Features of Sentence Template Codes below.

Role Holders (if plural)

Code: {role(plural)=____}

Again, this code behaves exactly like the code {role=____} above, except that it will return nothing unless more than one person qualifies to be in the list. This means that an expression such as "<the bridesmaids were {role(plural)=bridesmaid}>" will be blank in its entirety, if there were no bridesmaids, or just one.

The 'role(plural)' code can be qualified to specify a particular name format. See Advanced Features of Sentence Template Codes below.

Other Role Holders

Code: {other=____}

Witness sentences only. This code behaves exactly like the code {role=____} above, except that the current witness is excluded from the list of people. This makes it possible to construct witness sentences like this "{individual} was a bridesmaid.< The other bridesmaids were {other=bridesmaid}.>."

The 'other' code can be qualified to specify a particular name format. See Advanced Features of Sentence Template Codes below.

Other Role Holder (if singular)

Code: {other(single)=____}

Witness sentences only. This code behaves exactly like the code {role(single)=____} above, except that the current witness is excluded from the list of people.

The 'other(single)' code can be qualified to specify a particular name format. See Advanced Features of Sentence Template Codes below.

Other Role Holders (if plural)

Code: {other(plural)=____}

Witness sentences only. This code behaves exactly like the code {role(plural)=____} above, except that the current witness is excluded from the list of people.

The 'other(plural)' code can be qualified to specify a particular name format. See Advanced Features of Sentence Template Codes below.

All Other Witnesses

Code: {others}

Will be replaced by a list of all witnesses for the current fact, irrespective of role, excluding the current witness.

Formatting Codes

Formatting codes are used to control the presentation of information.

New Line

Code: <br>

Forces a new line to be started.

New Paragraph

Code: <para>

Forces a new paragraph to be started.

Sex-Version Codes

It is possible to have two versions of your template: one for males and one for females. To achieve this, two special codes are required:

Code: <male:> .... <female:> ...

The second code is optional. The first code <male:> must be the first item in the template. The male version template starts immediately after the male version code and is deemed to be terminated by the <female:> code, if supplied, or by the end of the template if not. The female version template starts immediately after the female version code, if supplied, and is terminated by the end of the template.

This is an example of the use of these codes:

<male:>{individual} injured himself {date} {place}<female:>{individual} injured herself {date} {place}

The male version template is "{individual} injured himself {date} {place}". The female version template is "{individual} injured herself {date} {place}".

If there is no female version code, the male version template will be used for everyone (but the male version code is redundant in that case). If both version codes are supplied, the female version template will be used for everyone whose sex is female, and the male version code will be used for everyone whose sex is either male or unknown.

Advanced Features of Sentence Template Codes

How to Use a Specific Date Format

The {date} template code can be qualified to specify a particular required format. To qualify the date code, add a colon followed by the qualifier. For example, the code {date:YEAR} will return the year part (only) of the date. The code {date:ABBREV3} will return the date in ABBREV3 format. The code {date:DAY_OF_WEEK} will return the day of the week of the date. See Date Formats for a complete list of qualifiers and the date formats they produce.

Please note that the simple {date} code automatically adds various prefixes (different ones depending on the date type) and other language elements, to make the date information fit correctly into a narrative sentence. When you qualify a date, no such additional language elements are added. If you want prefixes, you will have to add them yourself (see next).

How to Use a Specific Name Format For Role Codes

The following role codes can all use name qualifiers: 'role', 'role(single)', 'role(plural)','other', 'other(single)', and 'other(plural)'. To qualify the role code, add a colon followed by the qualifier after the code label, and before the equal sign. For example, the code {role:GIVEN=bridesmaid} will return the given name only of the person who has role 'bridesmaid' for the given fact. If more than one person has that role, the expression will return a list of all the given names of the relevant people. The code {other(plural):SURNAME=beneficiary} will return a list of the surnames of the people who have the role 'beneficiary' (e.g. of a will), who match the 'other(plural)' code (see above). See Name Formats for a complete list of qualifiers and the name formats they produce.

How to Add a Prefix or Suffix to Any Sentence Template Code

If a given field has no value the template code will be simply removed from the sentence that is output, without being replaced by anything.

For example, if you had a template:

{individual} was born at {address} {date}

and you had no address information for John Smith, the sentence generated for his birth event might be, say,

John Smith was born at on 19 January, 1903.

Notice the unwanted occurrence of the word 'at'. To avoid this happening you need to attach the 'at' to the address as a prefix, so that it only appears when there is an address. You do this by putting angle brackets <> around the code. Any text within the angle brackets will only be output if the code is not empty. So for example, if you changed the code to

{individual} was born <at {address}> {date}

the sentence generated would be

John Smith was born on 19 January, 1903.

and the unwanted 'at' would no longer appear.

You can use this technique to add a prefix and/or suffix to any code. Formatting codes may be included within the angle brackets if required. So, for example,

<<para>{note}<para>>

is valid and ensures that if a note is added, a new paragraph will be inserted before and after it.

Smart Spacing

In the example of John Smith's birth above, it might seem that you would get two spaces after the word 'born', if there were no address. In fact, you only get one. This is because Family Historian intelligently handles spacing for you. If it didn't do so, you couldn't use expressions like "{date} {place} {age}". Instead you would need to use (don't do this!) "< {date}>< {place}>< {age}>". By managing spacing intelligently, Family Historian makes it possible for expressions to be simpler and more readable; and there are other advantages. A common mistake is to try to manage spacing yourself when using angle bracket expressions, by leaving a space after the first angle bracket, and no space before it. Doing so, will disrupt Family Historian's ability to manage spacing for you. Instead, to ensure normal spacing with an angle bracket expression, you should leave a single space before the first angle bracket, and no space after it - as in the example above ("... <at {address}> ...").

How to Add Data References or Functions to Sentence Templates

This section describes advanced features. It is primarily intended for advanced and technically-minded users (especially the part about functions). In other words - please do not be discouraged if it makes no sense to you. These features are only needed if you have complex and advanced requirements that cannot be met using standard sentence template codes.

Data references and functions are both advanced features. The former are described in Understanding Data References and the latter are described in Understanding Functions. You can add data references or functions to sentence templates. Doing so allows you to reference any field associated directly or indirectly with the current context. When inserted into narrative sentences, data references must be wrapped within curly brackets {}. This is in addition to the percentage signs that ordinarily wrap data references. Although data references can be typed 'by hand', you are strongly recommended to use the Data Reference Assistant dialog to insert them wherever possible, as it will make it much easier to get the results you want. For example, to open the Data Reference Assistant dialog when editing a sentence template in the Fact Definition dialog, click on the << Insert Code button to the right of the Sentence Template field and then choose Data Reference from the dropdown menu that appears. To open the Fact Definition dialog, incidentally, click on Fact Types on the Tools menu, select the fact type you wish to edit and press the Edit button. The Data Reference Assistant dialog is not available if you choose to edit the Sentence field by hand (that is, override the template) in the Fact tab of the Property Box. In that case, you would have to type data references by hand if you wish to use them. Functions must always be typed by hand.

Data references that reference the current event or attribute itself, or a sub-field of it, begin with the 'FACT' tag. Some examples are shown in the table below. Please note that in the first two examples, there is a standard sentence template code which is the equivalent to the data reference. Where you can use a standard sentence template code instead of a data reference, you are recommended to do so as the former are simpler and therefore easier to understand.

Data Reference*	Meaning
{%FACT.DATE%}	Date of the current fact (i.e. equivalent to {date}). Example: "{individual} was born {%FACT.DATE%}"
{%FACT.NOTE2%}	Note about the current fact (i.e. equivalent to {note}). Example: "{individual} was born {date} {%FACT.NOTE2%}"
{%FACT.NOTE2.SOUR>%}	First source for the note about the current fact. Example: "{individual} was born {date} {note} <(source: {%FACT.NOTE2.SOUR>%})>". Note: as this example iillustrates, you can use angle brackets with data references and functions, to add prefixes or suffixes. See How to Add a Prefix or Suffix to Any Sentence Template Code above. In the example, the prefix is "(source:" and the suffix is the closing bracket, ")".
{%FACT.PHON%}	A phone number associated with the current fact. Example: "{individual} was resident {date} {place} <(tel: {%FACT.PHON%})>"
{%FACT.PLAC>LATLONG%}	{%FACT.PLAC>LATLONG%} Latitude and longitude of the place at which the fact occurred. Example: "{individual} was born {date} {place} <(lat/long: {%FACT.PLAC>LATLONG%} )>"

^{* As
always if you try these out, please remember that data references
only return data if the data has been recorded. If there is no
telephone number recorded for a given fact, for example, any data
reference for it will return nothing.}

What if you want to reference more detailed information about the principal in an event (or attribute) than you get using a standard sentence template code? In that case, you must use a contextual data reference – specifically one that begins CUR_PRIN - as in {%CUR_PRIN%}. That expression is similar to the standard code {individual} but there are some important differences. First, {individual} will often in practice be replaced by 'he' or 'she' when a sentence is generated . That will not happen with {%CUR_PRIN%}. Second, in a witness sentence, {individual} refers to the current witness, whereas {%CUR_PRIN%} still refers to the principal (or the first principal, if there are two) in the current fact.

Some facts (such as a marriage or divorce event) have more than one principal. To refer to the second principal, there is another contextual data reference: CUR_PRIN2. The expression {%CUR_PRIN2%} is similar to the standard sentence template code {spouse/her/him} but the latter will often be replaced by 'her' or 'him' when a sentence is generated and that will not happen with {%CUR_PRIN2%}. Also, {spouse/her/him} cannot be used in a witness sentence, whereas {%CUR_PRIN2%} can - it refers to the second principal (or nothing, if there isn't one).

As we have seen, both CUR_PRIN and CUR_PRIN2 can be used in both principal and witness sentences. There is also a third type of contextual data reference, beginning CUR~WITN, which can only be used in the context of a witness sentence – to refer to the witness. The table below gives some examples of all three:

Data Reference*	Meaning
{%CUR_PRIN%}	Current or first principal. Example: "{%CUR_PRIN%} was born {date}".
{%CUR_PRIN2%}	Other or second principal (i.e. equivalent to {spouse}. Example: "{%CUR_PRIN%} married {%CUR_PRIN2%} {date}".
{%CUR_PRIN.FAMC>HUSB>%}	Current or first principal's father
{%CUR_PRIN.FAMC>WIFE>%}	Current or first principal's mother
{%CUR_PRIN.FAMC>HUSB>FAMC>HUSB>%}	Current or first principal's paternal grandfather
{%CUR_PRIN.FAMC>HUSB>FAMC>HUSB>NAME:SURNAME%}	Current or first principal's paternal grandfather's surname
{%CUR_PRIN2.BIRT.DATE:YEAR%}	Other or second principal's year of birth
{%CUR~WITN>%}	Current witness (witness sentences only)
{%CUR~WITN.ROLE%}	Current witness's role in the current current event (witness sentences only)
{%CUR~WITN.NOTE2%}	Note about current witnesses role in the current event (witness sentences only)
{%CUR~WITN>NAME:SURNAME%}	Current witnesses' surname (witness sentences only)
{%CUR~WITN>FAMC>HUSB>NAME:SURNAME%}	Current witnesses' father's surname (witness sentences only)

The concept of a function will be familiar to everyone who has ever done any programming or written scripts using scripting tools. When you use a function in the context of a sentence template, the function call must be wrapped within curly brackets, just as data references are. The start of a function call is always marked by an equals sign; so this must come immediately after the opening curly bracket. A typical function call will take a number of parameters. The arguments to these parameters will often be data references, or other function calls. You can't use a standard sentence template code as an argument to a function.

Family Historian has over 100 functions (sometimes called 'built-in' functions to distinguish them from the Family Historian API functions), providing a wide variety of services. The table below gives just a handful of examples of what you can do. To learn more, see Understanding Functions.

Function call	Meaning
{=TextPart(%FACT.PLAC%, 2)}	The 2nd comma-separated part (if there is one) of the place where the current event or attribute occurred. For example, if the relevant place was "Glen Park, San Francisco, California, United States", this call would return 'San Francisco' and would work in any narrative sentence template. See the TextPart help for more details on using this function.
{=TextPart(%CUR~WITN>BIRT.PLAC%, -2)}	The second-last comma-separated part of the birth place of the current witness. For example, if the witness was born in "Glen Park, San Francisco, California, United States", this call would return 'California'. This example uses a contextual data reference that will only work in the context of a witness sentence. See the TextPart help for more details on using this function.
{=GetLabelledText(%CUR~WITN.NOTE2%, "Occupation:")}	The 'GetLabelledText' function returns the section of a note (up to the end of the paragraph) that follows the specified label – in this case 'Occupation:'. So, for example, if you used the Census event to record each person mentioned in the census as a witness, you could add a note for each witness and record their occupation in the note on a line beginning 'Occupation:'. Then you could use the expression on the left to insert the recorded occupation for each witness into the relevant witness sentence. You could record other details such as age in the same note, and reference them using the same technique, but with a different label (e.g. 'Age:'). The example also uses a contextual data reference that will only work in the context of a witness sentence. See the GetLabelledText help for more details on using this function.
{=TextIf(%CUR~WITN>SEX% = "Male", "his", "her")}	The 'TextIf' function returns a different result depending on a condition. In this example, the function will return the word 'his' if the current witness is male, and 'her' if the current witness is female. This example also uses a contextual data reference that will only work in the context of a witness sentence. See the TextIf help for more details on using this function.
{=RecordId(%CUR_PRIN%)}	Inserts the record id of the current or first principal for the current event or attribute. Will work in any narrative sentence template. See the RecordId help for more details on using this function.
{=RecordId(%CUR~WITN>%)}	Inserts the record id of the current witness. Uses a contextual data reference that will only work in the context of a witness sentence. See the RecordId help for more details on using this function.

The Escape Character

Occasionally you may wish to prevent a character from having a special meaning. To do this, place '\' in front of the character. For example, if you want the word "{date}" to appear exactly like that and not be treated as a code, write it like this "\{date}". The word "{date}" (without the escape character) will be output. Even the escape character itself can be 'escaped' in this way.