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.

Overview

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

• The changes occur with the introduction of TMG Version 9.02.
• The changes involve only the output of Role Variables.
• The changes involve only the output when the Role Variable refers to the subject of the Sentence.
• The changes impact the output only when more than one person in that Tag has that same Role.
• When Projects created in earlier versions are opened in a newer version, an automatic conversion process solves most issues to ensure unchanged Sentence output for most users.
• Users who write Sentences using Role Variables need to become aware of the new behavior of certain variables.
• A few advanced users may need to make some manual changes, as described later in this article.

These points are discussed in more detail below.

Do I Need to Understand This?

The changes described here have no impact on most users!

• If you use only Default Sentences – these changes have absolutely no impact on your use of TMG. Read on only if you find such things interesting.
• If you write your own Sentences – and use only the [P], [PF], [PG], [W] or similar Variables, the changes have no impact on you. For example, if you write Sentences like this Sentence for a Groom Role in a Marriage Tag:

the changes have no impact on you.

• If you write your own Sentences – and you always refer to the subject of the Role with a [P], [PF], [PG], [W] or similar Variable while using Role Variables for other people, the changes have no impact on you. For example, if you write Sentences like this Sentence for a Groom Role in a Marriage Tag:

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.

• If you write your own Sentences – and you sometimes refer to the subject of the Sentence with a Role Variable referring to the subject's Role, like this Sentence for a Groom Role in a Marriage Tag which uses a Groom variable:

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

• If you use Role Variables in Memos – you 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:

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:

• When [R:rolename] is used in the Sentence to refer to the subject of that Role that variable will be converted to [S]. This ensures that the output of the Sentence will remain the same – the name of only the subject of this Sentence when more than one person in the Tag is assigned this Role. This applies to both Tag Type and Local Sentences. For example, the following Sentence that might be used for the Role of Groom in a Marriage Tag:

will be converted to this:

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 [RA:rolename] and [RE:rolename] refer to the subject of the Role they will also be changed to [SA] and [SE]. This change is being made because lists of ages, which can occur if more than one person is assigned the Role in the Tag, seldom make sense and thus were probably not intended.

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:

• Use of [RF:rolename], [RG:rolename], [RL:rolename], etc. in Tag Type Sentences when the Variable refers to the subject of the Sentence, and the Role is used for Principals. This does not apply to use of the [R:rolename] Variable because that case is addressed by the automatic conversion process, but only to Variables which produce selected name parts.

• Use of [RF:rolename], [RG:rolename], [RL:rolename], etc. in Local Sentences for Principals when the Variable refers to that Principal. This case does not apply to use of the [R:rolename] Variable because that case is addressed by the automatic conversion process, but only to Variables which produce selected name parts.

• Use of [R:rolename], in Tag Memos when that Memo is referenced by the Sentence of a Principal or a Witness, and that Variable refers to that Principal or Witness. Use of the Variables in Memos to refer to other people is not an issue.

• Use of [RF:rolename], [RG:rolename], [RL:rolename], etc. in Tag Memos when that Memo is referenced by the Sentence of a Principal, and that Variable refers to that Principal. Use of the Variables in Memos to refer to other people is not an issue.

• Use of [R:rolename] in Witness Memos when that Memo is referenced by the Sentence of the Witness, and that Variable refers to that Witness. Use of this Variable in Witness Memos to refer to other people is not an issue.

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:

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

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."

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.

Copyright 2000- by Terry Reigel