Terry's TMG Tips

Changes in Role Variables

This page created 10 Jul 2014

Version note: Applies to TMG 9.02 and later

This article describes changes in the behavior of certain Role Variables introduced with TMG version 9.02. Users who have created Sentences using Role Variables to refer to the subject of those Sentences, or intend to in the future, need to be aware of these changes.

My article on Modifying Tag Sentence Structures provides an overview of writing and modifying the Sentence Structures in Tags and my group of articles on Using Roles provides more specific information about that subject. My article on Sentence Variables for People provides more detailed information about that group of Variables, including the ones discussed here.

Tags in TMG have one or two people entered as Principals, and any number may be entered as Witnesses. Each of those people has an associated Sentence Structure, which controls how information from the Tag appears when a narrative report is created for that person. That person can be said to be the "subject" of that Sentence. The issues discussed here involve the use of Role Variables to refer to the subject person of the Sentence.

Topics Included in this Article
Overview
Key points about the changes
Do I Need to Understand?
Understanding whether the changes impact you
What Are the Changes?
Understanding exactly what is changing
Automatic Conversion
Automatic conversion during upgrade
Writing New Sentences
Issues to be aware of when writing new Sentences with Role Variables
Advanced User Issues
Issues that may be encountered by advanced users
Change Log
Examining the changes made by the automatic conversion process
Second Site Conversion
Information for Second Site users

Overview

The changes discussed here can be summarized by the following points:

These points are discussed in more detail below.

Do I Need to Understand This?

The changes described here have no impact on most users!

[P] and [PO] were married< [D]>< [L]>

the changes have no impact on you.

[P] and [PO] were married< [D]>< [L]>< with [R:Minister] officiating>

the changes have no impact on you. Note that in the second example the Role Variable [R:Minister] is used to refer to someone other than the subject of the Sentence. As long as you use Role Variables only to refer to people other than the subject of the Sentence these changes do not impact you.

[R:Groom] and [R:Bride] were married< [D]>< [L]>

you do need to read on to see what impacts the changes may have on your Project.

What Are the Changes?

The changes being made involve only Role Variables – [R:Bride], [RF:Head of Household], [RG:Heir], etc. They impact these Variables only when they refer to the subject of the Sentence, that is the person who is assigned the Role for which the Sentence is being written. Further they impact the output only when that Role is assigned to more than one person in the Tag. The following tables describe the output before and after the change:

Output of Name Role Variables – Old Rules
TMG 9.01 and prior
Full Name Variables:
[R:rolename]
Name Part Variables:
[RF:rolename], [RG:rolename], etc.
When Used in Sentence of a Principal to Refer to that Principal:
Name of that one Person Name of that one Person
When Used in Sentence of a Witness to Refer to that Witness:
Name of that one Person List of all People with Role
When Used to Refer to People with a Different Role:
List of all People with Role List of all People with Role

 

Output of Name Role Variables – New Rule
TMG 9.02 and later
[R:rolename] [RF:rolename], [RG:rolename], etc.
List of all People with Role List of all People with Role

The new rule is simpler, and provides consistent output in all situations, making it easier to obtain the expected results. It also allows forms of output not possible before, such as including the names of all persons assigned the Role of the subject of the Sentence if that is desired. However, the transition requires some attention for projects that have depended on the old rules for the desired output, or in some cases unintended output may result. These considerations are discussed next.

Automatic Conversion Process

When a Project that has been created in an earlier version of TMG is first opened in TMG 9.02 or later an automatic conversion process reviews all Sentences and makes changes which adjust to the new rules so that the output of the Sentence will remain unchanged. Users are offered the choice to have the conversions made or not with this screen:

In almost every case users should click Yes to allow the conversion so that most Sentence output will remain unchanged. A few advanced users may prefer to make all the conversions themselves or may output only in Second Site and use the option there that mimics the new behavior in TMG, and so would choose No. There is no way to activate the conversion later if the choice is declined when first offered, other than to open another copy of the Project that has not previously been opened in the new version.

When the conversion proceeds, TMG will examine all the Sentences in the Project and will make the following changes:

[R:Groom] and [R:Bride]<[RPAR:Bride]> were married< [D]>< [L]>
will be converted to this:
[S] and [R:Bride]<[RPAR:Bride]> were married< [D]>< [L]>

Note that only the Role Variable referring to the subject of the Sentence, in this case the groom, is converted. There is no change to any other Role Variables

When the conversion process is completed a log of all changes made is created. Most users will not need to examine it, but for those who may wish to it is described in the Change Log section below.

Writing New Sentences with Role Variables

After your Project is converted to work with the modified behavior of Role Variables, you need to keep these changes in behavior in mind as you write new Sentences in which you might use Role Variables.

The "rule" is simple: do not use Role Variables to refer to the subject of the Sentence. Instead, use "subject" Variables or "position" Variables to refer to the subject person. There are two exceptions to this rule:

  1. When you actually do want a list of all people entered in the Tag who are assigned the Role rather than just the name of the subject person.
  2. When you are very sure there will never be more than one person entered in the Tag with that Role. Even then, in my opinion, it is better practice to use "subject" Variables, or "position" Variables.

For more information on this see my Sentence Variables for People article.

Issues for Advanced Users

Some advanced users may encounter issues related to the change in behavior of the Role Variables that are not resolved by the automatic conversion process described above. The five cases where this might occur, arranged in my judgement in order of decreasing likelihood are as follows:

As seen in the Rules table above, in each of these cases when the Role Variable refers to the subject of the Sentence and that Role is assigned to more than one person, previously only one name would be output but now all names will be output.

Note that all of these are an issue only if any one Tag will have more than one person assigned that Role. If the nature of the Role, such as "Bride," or your usage practices, limit the Role to only one person in any one Tag these usages will not be an issue.

Each of these issues, methods of identifying any potentially troublesome instances in a Project, and suggestions for possible changes are discussed in my Changes in Role Variables – Advanced Issues article.

Change Log

When the automatic conversion process is allowed to run a log is created listing all changes made. The log is located in the same folder as the Project files, and has a file name similar to "_Role_conversion_(2014.04.14_13-48-50).log" where the numbers indicate the date and time the conversion was made. The log can be opened with a text reader such as NotePad, which is built into Windows.

When you open the log you see something like the following. First is the date and time of the conversion, and the name of the Project, followed by a brief description of the process:

14-04-14, 13:48:50 >Project: d:\TMG\Data\Projects\Terrys Main__.PJC
>--------------------------------------------------------------------------
>Only some of the new Subject variables have Rx:Role equivalents and
>those need to be converted when an older project is open.
>.
>Specifically, let's say that a person has a role of "Abcde" in an event
>(but it is true for any role that he might have). Then any reference to
>these variables IN HIS SENTENCE should be converted:
>.
> [R:Abcde] -> [S]
> [RA:Abcde] -> [SA]
> [RE:Abcde] -> [SE]
>.

Next is a section listing all changes made to Global, that is Tag Type, Sentences:

> Global sentence. (table T)
>___________________________________
> 1) Tag type "Land b/s", Role "Buyer"
>before "[R=Buyer][R:Buyer] bought <[M1]> <[L]> from [R:Seller] <[D]><, [M2]>"
>after "[R=Buyer][S] bought <[M1]> <[L]> from [R:Seller] <[D]><, [M2]>"
>___________________________________
> 2) Tag type "Land b/s", Role "Seller"
>before "[R=Seller][R:Seller] sold <[M1]> <[L]> to [R:Buyer] <[D]><, [M2]>"
>after "[R=Seller][S] sold <[M1]> <[L]> to [R:Buyer] <[D]><, [M2]>"
>.

For each Tag Type in which any Sentences were changed, there is an entry for each Role that is changed. The log shows for each the Tag Type Label and the Role label, each marked in red above. Then the Sentence is shown, both before it is modified and after modification, with the changes also marked in red above. This section may be quite long if many Tag Types had Sentences that needed modification.

Next is a section listing all changes made to Local Sentences, that is Sentences entered in individual Tags. Note in this context the heading "Witness sentences" means all local Sentences, both for those people entered as Principals and those entered as "Other Witnesses."

> Witness sentence. (table E)
>___________________________________
> 3. Tag type: "Land b/s", Role: "Buyer" , Person: 1:14048
>before "[L=ENGLISH][R:Buyer] bought <[M1]> <[L]> from his son [P1GS] estate <[D]> <[M2]>"
>after "[L=ENGLISH][S] bought <[M1]> <[L]> from his son [P1GS] estate <[D]> <[M2]>"
>___________________________________
> 4. Tag type: "Land b/s", Role: "Seller" , Person: 1:8271
>before "[L=ENGLISH][R:Seller] sold <[M3]> to his brother [RF:Buyer] <[D]>. [M2]"
>after "[L=ENGLISH][S] sold <[M3]> to his brother [RF:Buyer] <[D]>. [M2]"
>___________________________________

For each Tag in which any Local Sentences were changed, there is an entry for each person whose Sentence was changed. The log shows for each the Tag Type of the Tag, the Role assigned to the person, and the person's ID number, each marked in red above. Then the Sentence is shown, both before it is modified and after modification, with the changes also marked in red above. This section may be quite long if many Tags had Local Sentences that needed modification.

Converting Second Site

Second Site, the program that creates great websites from TMG data, has long had an option to produce output from Role Variables as TMG does starting with version 9.02. By default, that option has been set to mimic the prior behavior of TMG, and most users have left that setting so that the narrative output in TMG reports and websites created with Second Site would be the same. Version 5.3.0 of Second Site will automatically change that setting of agree with the new behavior of TMG if a Project opened in TMG 9.02 or later is being used. Users of TMG 9.02 or later should upgrade their installation of Second Site to version 5.3.0 if they have not previously done so.

Those using older versions of Second Site can make the same change manually by setting the "Subject Role Rule" option in the Data > Names section to "All people with role (SS)," as shown below:

Users creating more that one website with Second Site (that is, having more than one SDF file) will need to make this change for each SDF file.

Conclusion

Many, or even most, users are not impacted by the changes in the output of certain Role Variables because they do not use those Variables. For most users who do use them the automatic conversion process will prevent any changes in output, if any would result otherwise. Users of Role Variables need to be mindful of the new behavior when writing new Sentences with those Variables.

Only a few users may have made use of techniques which the automatic conversion process does not address and thus will have to review their Projects themselves. Any users who think they may fall in this category may also want to see my Changes in Role Variables – Advanced Issues article.


ReigelRidge Home Terry's Tips Home Contact Terry

 

 

Copyright 2000- by Terry Reigel