Sentence Template Language

From RootsMagic Wiki
Jump to navigation Jump to search

Navigation: RootsMagic 8 > Working With Facts > Fact Sentences >

Note: This help item is common to both Fact Sentence templates and Source templates. Some items are applicable to only one of the two template types.


Sentence templates allow you to tell RootsMagic how to write a sentence for a given fact or source citation. You simply write a sentence with "fields" and “switches” to show where things like names, dates, and places fit. Square brackets [ ] indicate the name of a field to be displayed, while angle brackets < > indicate a switch, or conditional statement, that will determine what, if any, data is displayed.

There are two types of templates: Fact Sentence Templates and Source Templates. Fact Sentence Templates are used when a particular fact is written in a narrative report or website. Source Templates are used when a source citation is written in a report or a website. While each type of template has its own unique features, they both share the same basic usage and rules.

Fields

Fields are pieces of a template that are replaced with meaningful text at the time the sentence is written. They are written using square brackets with the name of the field inside. Field names are not case sensitive, so for example, [Date], [date], [daTe], [DATE] are all equivalent field names. Through out this topic, most have the first letter Capitalized so they stand out, especially when several words are used together like PlaceDetails. Fields in a fact sentence template may look like this:

[Person] was born< [Date]>< [PlaceDetails]>< [Place]>.

In this example, when RootsMagic encounters a person’s birth when writing a narrative report, it takes this template and replaces [Person] with the person’s name, [Date] with the date of the birth, [PlaceDetails] with the details (hospital or address) within the place where the birth occurred, and [Place] with the place (city, county, state, country) of birth.

Fields in a source template for the full (first) footnote may look like: 

[Author], <i>[Title]</i> ([PubPlace]: [Publisher], [PubDate]).

while the fields in a source template for the bibliography might look like: 

[Author:Reverse]. <i>[Title]</i>. [PubPlace]: [Publisher], [PubDate:Year].

In this example, when RootsMagic encounters a book source, it replaces the source fields [Author] with the author of the book, [Title] with the title of the book, [PubPlace] with the place of publication, [Publisher] with the name of the publisher, and [PubDate] with the date of publications (usually a year.) You will also note the and formatting codes which tell RootsMagic to format the text in italics font, :Reverse tells RootsMagic to show the surname first, and :year tells RootsMagic to show only the year part of the date.

Fact Sentence Fields

Fact sentence templates are created using a combination of pre-defined fields referring to a person or persons, pre-defined fields referring to fact details, as well as plain text and punctuation. Formatting codes can be used in Fact sentence templates, if desired, but are more commonly used in the Notes field to emphasize a portion of the note text. The field names and field options in templates are not case sensitive – they can be all lower case, all upper case, or first letter of each word capitalized, etc. First letter capitalization is used here, particularly where multiple words are involved, to make it easier for people to read.

The pre-defined fields for use in fact sentence templates are:

Field Field Type Description
Fields referring to a person or persons:
[Person] 1 person The principal person of the event
[Spouse] 1 person The spouse of the principal person
[Couple] 1 or 2 people Both the principal person and spouse, if entered
[Husband] 1 person The husband in the principal person’s marriage
[Wife] 1 person The wife in the principal person’s marriage
[ThisPerson] 1 person The main witness that the witness sentence is about. Witness fact sentences only.
[OtherPersons] 1 or more person All witnesses to the event, regardless of role. In witness fact sentences, this excludes the main witness.
[Role] 1 or more person All witnesses to the event with the specified role. The name of the role is typed in square brackets, e.g. [Witness], [Doctor], [Minister]
[Field(#)] 1 person In the case of fields that refer to more than one person, you can refer to a specific person by number by writing the number in parentheses after the field name. For example, to get the 3rd bridesmaid, type [Bridesmaid(3)].
[Field 1,Field 2,…] 1 or more person Any number of person fields may be combined into a single group by writing all the field names within square brackets, separated by commas. For example, to get all the groomsmen and bridesmaids, type [Groomsman,Bridesmaid].
Fields referring to fact details:
[Date] Date The date of the event
[Place] Place The place where the event happened
[PlaceDetails] Place Details about the place where the event happened (for example, the name of the church or cemetery, or the street address)
[Desc] Description The description of the fact

Source Fields

Source fields are defined for each source template. To use that field in a template, type its name in square brackets, or you can drag the field from the field list into the respective template (full footnote, short footnote or bibliography). A source template is made up of source fields, plain text and punctuation, as well as formatting codes when required.

Field Options

You can set options for every field that control both what is written and how it is written. You type the options within the field’s square brackets. You can add as many options as necessary to a field, each option separated by a colon, but no extra spaces. For example:

[Witness(4):Surname:Caps]

[Person:Given:Surname]

[PublishDate:Year]

[Place:Reverse:Proper]

Option Field Type Description
Capitalization Options
:NoCaps Any Default. Makes no changes in capitalization.
:Upper Any Changes to upper case, e.g. “JOHN DOE”
:Lower Any Changes to lower case, e.g. “john doe”
:Caps Any Capitalizes the first letter and makes no changes to subsequent letters, e.g. “John doe”
:Proper Any Forces “proper” capitalization, e.g. “John Doe”
Abbreviation Options
:NoAbbrev Source Template Default. Look for a "||" and process the information that precedes it, e.g. Post Office Box 1010 "||" PO Box 1010 = Post Office Box 1010
:Abbrev Source Template Look for a "||" and process the information that follows it, e.g. Post Office Box 1010 "||" PO Box 1010 = PO Box 1010
Name Part Options (May include one or more)
:Full Name & Witness names Dr. John Robert “Johnny” Doe Jr.
:Reverse Name & Witness names Doe, Dr. John Robert “Johnny” Jr. (reverses first name in a group only)
:Given Name & Witness names John Robert
:First Name & Witness names John
:Surname Name & Witness names Doe
:Prefix Name Dr.
:Suffix Name Jr.
:Nickname Name Johnny
:Casual Name & Witness names Nickname, if known, otherwise first name
Age Options
:Plain Age No prefix.
:At Age “at the age of Age”. Default for fact/role sentence ages
:Commas Age “, age Age,”
Fact Place Options
:Original Place in Fact/Role Sentences Original version of place (default), e.g. “Brownsville, Utah Territory”
:Short Place in Fact/Role Sentences Abbreviated version of place, e.g. “Ogden, Utah”
Place Options
:Full Place or Place Details in source template or fact/role sentence Ames, Story, Iowa, United States
:Reverse Place or Place Details in source template or fact/role sentence United States. Iowa. Story. Ames
:ReverseComma Place or Place Details in source template or fact/role sentence United States, Iowa, Story, Ames
:First Place or Place Details in source template or fact/role sentence Ames
:Last Place or Place Details in source template or fact/role sentence United States
Place & Description Prefix Options
:Plain Place, Place Details, or Description No prefix. Default for source templates and description fields
:In Place, Place Details, or Description “In Text”. Default for fact/role sentence places
:At Place, Place Details, or Description “At Text”. Default for fact/role sentence place details
:A Place, Place Details, or Description “A Text” or “An Other text”
Date Options
:Plain Date Full date, e.g. “6 Apr 1830”, no "in" or "on" prefix. (Default for source templates)
:InOn Date “on 6 Apr 1830” or “in Apr 1830”. (Default for fact/role sentences.)
:Year Date Year only, e.g. “1830”
:DayOfWeek Date Show the day of week with the date, e.g. “Tuesday 6 Apr 1830”
:NoDayOfWeek Date Removes the day of week from the date (default)
:Commas Date Adds commas to the date, e.g. "6 Apr, 1830” or “Tuesday, 6 Apr, 1830”
:NoCommas Date Removes commas from the date (default)
Person Options
:Name Fact Sentence People Default. The names of the people in roles
:Poss Fact Sentence People Possessive form of names, e.g. John's. To get the full name possessive, i.e. “John Doe’s”, you would enter [Person:Full:Poss]
:HeShe Fact Sentence People He/She/They
:HisHer Fact Sentence People His/Her/Their
:HimHer Fact Sentence People Him/Her/Them
:Age Fact Sentence People Age of person at time of event
:Role Fact Sentence People Role of witness
:Count Fact Sentence People # of people in the group, i.e. [role1,role2,role3:count], e.g. [child:count] or [son,daughter:count]
Person Name Cycling Options
:Cycle Fact Sentence People Prints the full name first and then cycles between He/She and the casual name in subsequent uses. Default for “Person” and “Couple” in regular fact sentences and default for “ThisPerson” in witness fact sentences.
:NoCycle Fact Sentence People Print the name as specified without cycling

Formatting Codes

Formatting codes allow you to tell RootsMagic how you want the font to look in the report. Formatting codes are contained inside of a left angle bracket "<" and right angle bracket ">". They are used in pairs - the first tells RootsMagic to turn on the formatting, and the second, with a "/" after the left angle bracket (</ >) to turn off the formatting. For example: 

<i>[Title]</i>
The <i> and </i> formatting codes tell RootsMagic to display the title in italics font.
Field Field Type Description
Formatting Codes 
<i> ... </i>
 Fact sentence and Source templates, fields, and notes Displays the text in italics 
<b> ... </b>
 Fact sentence and Source templates, fields, and notes Displays the text in bold 
<u> ... </u>
 Fact sentence and Source templates, fields, and notes Displays the text in underline 
<sc> ... </sc>
 Fact sentence and Source templates, fields, and notes Displays the text in Small Caps (upper case letters remain unchanged, lower case letters are changed to upper case, but in a smaller font) 
<sup> ... </sup>
 Fact sentence and Source templates, fields, and notes Displays the text in superscript 
<sub> ... </sub>
 Fact sentence and Source templates, fields, and notes Displays the text in subscript

Formatting codes can be nested within other formatting codes or switches, but cannot be included within the square brackets indicating a field.

Switches

A switch allows you to write different information, depending on the information that is available. Switches are contained inside of a less-than and greater-than sign (< >). Inside of the switch are any number of pieces, separated by a “|”. For example:

<First Piece|Second Piece|Third Piece|Fourth Piece>

You can set the kind of switch by using a special character after the first less-than sign. There are five special switch characters, ? for the Value switch, % for the Gender switch, @ for the Living switch, # for the Plural switch, and ! for the Private switch. For example:

<%actor|actress>

In a switch that depends on information about a person or a group of people, such as value switches, gender switches, living switches, and plural switches, you can specify which person or group of people the switch applies to by writing the field names of the people either immediately after the special character (living, plural) or enclosed in square brackets ([value], [gender]) and then followed by the special character again.

<#Doctors#doctor|doctors>

Two of the switches, Gender (%) and Living (@), will refer directly to the focus subject if a field name is not entered. For example:

<@He is living|He is not living>.

The Private switch (!) is used in source templates to privatize things such as a street address data that you want to record, but not make public. The trigger that activates the Private switch is a checkbox in the Sources, Options tab in the Report Settings dialog.

Simple Switches

A simple switch requires no special character and can have any number of pieces.

<First Piece|Second Piece|Third Piece|Fourth Piece>

RootsMagic will look at each piece, beginning with the first. If the piece has a field with a value, or has no fields, it is written and all the remaining pieces are skipped. For example, lets look at the basic birth sentence with conditional brackets added:

[Person] was born< [Date]>< [PlaceDetails]>< [Place]>.

The angle brackets < > indicate that if there is no value entered, neither the field nor the space before it will be shown. This applies to the [date], [placedetails] and [place] fields.

In the following source templates examples:

<privately held by [LastKnownOwner], >

would only write something if “[LastKnownOwner]” has a value, or in this example:

<[Format],|digital image,>

would write “database and digital images,” if that's what you entered into the [Format] field, or it would write "digital image,” if you didn’t enter anything into the [Format] field.

Value Switches

A value switch is similar to a simple switch except that it allows you to check for a value without actually writing that value. It is indicated by a “?”.

<?[Expression]| Show this if True.>

<?[Expression]| Show this if True. | Show this if False.>

<?[Expression]|| Show this if False.>

For example:

<?[Nurse]|He had a nurse.>

<?[Nurse]|He had a nurse.|He didn't have a nurse.>

<?[Nurse]||He didn't have a nurse.>

would check to see if the role of [Nurse] had a value. If it did, it would write “He had a nurse.” If it did not have a value, it would write “He didn't have a nurse.”

Note that what comes after the “?” is different from the gender and living switches. The gender and living switches need the role of a person or group of people followed by their special character. The value switch takes any expression including fields in brackets and other switches.

Gender Switches

A gender switch checks the gender of a person or group of people and writes the appropriate text. It is indicated by a “%”. It is of the form:

<% Males & Unknowns > or

<% Males & Unknowns | Females > or

<% Males | Females |Unknowns > or

<% Male | Female | Unknown | Multiples > or

<% Male | Female | Unknown | Male & Mixed Multiples | Female Multiples > or

<% Male | Female | Unknown | Male Multiples | Female Multiples | Mixed Multiples >

or it can take the form to process a list of one or more roles

<%roles%| Male | Female | Unknown | Male Multiples | Female Multiples | Mixed Multiples >

In this first example, the switch looks at the default [person]:

<%He was an actor.|She was an actress.>

In this second example, the switch looks at the role name [child]:

<%Child%[child] was a son.|[child] was a daughter.|[child] was a child.|[child] were sons.|[child] were daughters.|[child] were children.>

In the first example, the "person" is the focus person to which the sentence applies. In the second example, [child] refers to a role assigned to someone in a shared event. The role [child] could be assigned to one or more people.

Note: Roles, which are added as "Just type name of witness" menu, or "This person is NOT in the file" in Edit Share Event, do not have a gender, and may affect results of this switch.

Living Switches

A living switch checks if a person or group of people is living and writes the appropriate text. It is indicated by a “@”. It is of the form:

<@ Living > or

<@ Living | Not Living >

<@roles@ Show this if all Living | Show this if one or more Not Living >

For example:

<@He has brown hair.|He had brown hair.> (This assumes that his hair never turned gray.)

<@Doctors,Nurses@They are doctors and nurses.|They were doctors and nurses.>

Plural Switches

A plural switch looks at the number of people in a group and writes the appropriate text. It is indicated by a “#”. It is of the form:

<#roles# Single > or

<#roles# Single | Plural > or

<#roles# Single | Plural | None >

For example:

<#Doctors#His doctor was|His doctors were> [Doctor].

They had <#Children#a child|<[Children:count]> children|no children>.

There <#Heir1,Heir2#was one heir|was more than one heir|were no heirs>.

Private Switches

A private switch is used for fact sentence templates and source templates. For sources, this allows you to write different text depending on whether you have or have not checked the "Hide private data in the endnotes, footnotes, and bibliography" option in the Sources, Options tab, telling RootsMagic whether to display the private or the not private information for this switch. It is of the form:

<! NotPrivate | Private >

For example:

<!<[Address]>|(The address is private.)>.

If the checkbox is checked, "(The address is private.)" would print. If the checkbox was unchecked, the address data that was entered in the [Address] field would print, if one was entered, otherwise nothing would print.

Escape Characters

If you ever want to write an actual <, >, /, [, or ] in your sentence, you must precede it by a “/”. This tells RootsMagic that to print the following character and to not treat it as a switch or a field. For example:

[Person] /[This is in brackets/]. would print:

John Doe [This is in brackets].

and [person] is a /[person/] would print

John Doe is a [person].

thus allowing the keyword "person" to be enclosed within square brackets without being interpreted as a field.

Tip: To include a field value within square brackets, such as [John Doe], you can enclose the field within a switch with the square brackets outside the switch, i.e. [<[person]>].

Switches Within Switches

RootsMagic allows you to put switches within other switches, also known as nesting. This allows you to create very powerful and flexible sentence templates.

Retrieved from "http://wiki.rootsmagic.com/index.php?title=RootsMagic_8:Sentence_Template_Language&oldid=3331"