Terry's TMG Tips

Changes in Role Variables – Advanced Issues

This page created 10 Jul 2014

Version note: Applies to TMG 9.02 and later

This article describes issues that may arise for advanced users resulting from changes in the behavior of certain Role Variables introduced with TMG version 9.02. More general issues related to this change are describe in my Changes in Role Variables article.

The five cases described below are not addressed by the automatic conversion process, which is designed to resolve the issues that may be encountered by the vast majority of TMG users. These issues, if they exist in a user's data, must be addressed by the user. Suggestions for identifying cases are included for each issue.

Case 1: [Rx:rolename] Variables in Tag Types Sentences Assigned to Principals

This issue arises when Variables like [RF:rolename], [RG:rolename], [RL:rolename], etc. are used in Tag Type Sentences to refer to the subject of the Sentence, and that Role is assigned to Principals. The problem is that after the changes in the output of the Role Variables, if more than one person entered in the Tag is assigned that Role, a list of all of them will be output rather than just the name of the subject person.

There is no issue when:

• The [R:rolename] Variable is used, because that case is resolved by the automatic conversion process.
• The Role is assigned to Witnesses, because for Witnesses all names have always been output. (Unless that was not the intended result, in which case the previous use has been producing unintended output).
• The Role is not assigned to this Principal, thus the Variable refers to another person or persons entered in the Tag.
• The Role is never assigned to more than one person, either because by its nature, such as for "Bride" or "Groom," or because of the data entry practices of the user.

If you have Tag Types with this issue the solution is to change the [RF:rolename], etc. Variable to the corresponding subject Variable, such as [SF] in those Sentences. If you cannot recall such cases but suspect your Project may contain some you will have to review all the Tag Types in your Project for Roles which you might assign to both Principals and Witnesses. If any are found, review their Sentences to see if any use the [RF:rolename], [RG:rolename], [RL:rolename], etc. Variables to refer to the subject.

If the Roles found might sometimes have been assigned to a Principal and sometimes a Witness, there now is no way for a single Sentence to retain the old behavior of producing differing output for Principals and Witnesses, if that in fact was the intent. If you want the output to be the same in both cases, you will need to choose whether to retain the Role Variable to always output all names, or use the new Subject Variable to always output only the subject's name. If you want the option of outputting one name in some cases and all names in others, you will have to construct two separate Roles – one using the corresponding Subject Variables to output only one name, and a separate one using the Role Variables to output all names assigned this role. You will then have to assign the appropriate Role to each person to obtain the output desired.

You could do this by reviewing all the Tag Types in the Master Source List. But the review can be made considerably simpler by use of John Cardinal's TMG Utility to search for potential cases. (The TMG Utility is free, but is "donor ware," meaning John asks that you make a donation to his favorite charity if you find it useful.)

For this test, use the Export Data feature, as shown below, and then use your browser to examine the HTML file that is created:

As shown above, make the following settings:

• Set the "Data to Export" drop-down to Sentences
• Set the "Export format" drop-down to HTML
• Set the "Stylesheet" drop-down – I found the Standard style easiest to use
• Check the "Open output file" box so the file created will automatically open in your browser
• Check the "Log Only" box since we are only use the log to identify potential cases, not actually making any changes with the Utility

Click the "Export Data" button, and after specifying a location for the file that is to be generated, you see this dialog:

If you use only one Language for your Sentences, choosing that Language in the "Show Language" drop-down will eliminate Sentences in Languages you don't use. Otherwise, choose All or make separate runs for each Language.

When you click the OK button a file listing all the Sentences in your Project will be generated and will open in your browser. It will show each Tag Type and the Sentences for each Role. Here is an example for one of my Tag Types:

Here I have used the "Find" function in my browser (may be "Find in this Page" depending on which browser you use) to search for "[RF:" to find Sentences using the [RF:rolename] Variables. If you use other variations you would also search for them.

When you locate a Sentence that uses these Variables, first look at the Role to see whether it is one you might use for Principals. In this case I would only use the "Principal," "one Daughter," and "one Son" Roles for Principals, so I examine only those Roles to see if the [RF:rolename] Variable refers to the subject of the Role. In each of those three Roles above the [P] Variable is used to refer to the subject, so there is no issue with this Tag Type. I would continue to examine other Tag Types.

If you know you have used Variables like [RF:rolename], [RG:rolename], etc. to refer to the subject person of a Role in a particular Tag Type, and are unsure whether you may have assigned that Role to Principals, use the List of Events report with a Filter like the following (ver. 9.02 and later only) to find any such cases:

To check for multiple Rolenames at a time, the filter could use the vertical bar (OR) separator permitted with the Equals operator (e.g. SPOUSE|CHILD), or define multiple filter conditions using the OR connector.

Note that this example filter only identifies Tags where a Principal has been assigned the role of "Spouse".  It does not identify whether a "Spouse" Role Variable is used in the Sentence to refer to the Principal, nor that if so it is of the [Rx:rolename] type as opposed to the [R:rolename] type. Both would have to be determined by examining the Sentences in the Tags identified by the report.

This filtered report can be used to identify whether a specific Role is assigned to a Principal where that Role is not intended for such assignments.  It can also be used to identify whether a specific Role is assigned to a Principal when you know that Role uses an [Rx:rolename] Variable to refer to the subject of the Role.

Case 2: [Rx:rolename] Variables in Local Sentences of Principals

This issue arises when Variables like [RF:rolename], [RG:rolename], [RL:rolename], etc. are used in Local Sentences for Principals, and the Variable refers to that Principal. The problem is that after the changes in the output of the Role Variables, if more than one person entered in the Tag is assigned that Role, a list of all of them will be output rather than just the name of the subject person.

There is no issue when:

• The [R:rolename] Variable is used, because that case is resolved by the automatic conversion process.
• The Variable is used in Sentences for Witnesses, because for Witnesses all names have always been output. (Unless that was not the intended result, in which case the previous use has been producing unintended output.)
• The Role is not assigned to this Principal, thus the Variable refers to another person or persons entered in the Tag.
• The Role is never assigned to more than one person, either because by its nature, such as for "Bride" or "Groom," or because of the data entry practices of the user.

If you have Tags with this issue the solution is to change the [RF:rolename], etc. Variable to the corresponding subject Variable, such as [SF]. If you cannot recall such cases but suspect your Project may contain some, two methods are available which can aid in the search.

The first is to use the List of Events report to create a list of Events with Sentences which contain the Variables in question, then examine that report to identify any which refer to the subject person. A Filter such as the following may be useful:

If variations other than first name and given name may have been used to refer to the subject, lines should be added to the filter to search for them too. In Report Options, on the Output Columns tab, specify information to identify the Tags in question, and include as much of the Principal Sentence as possible to facilitate review of the Tags found. I have found the following arrangement of Output Columns useful:

* (ver. 9.02 and later only)

With those wide field specifications output of the report as an Excel spreadsheet seems to work best.

The report will allow you to see which Local Sentences contain Variables of the type at issue. You will have to review the Sentences to determine whether that Variable refers to the Role assigned the Principals. For example, you may see this Sentence:

Examination of the Sentence in this case shows that the Principal is referred to with the Variable [PF] and that the [RF:rolename] variable refers to someone else, so this Sentence is not an issue.

Another approach, which also identifies the Role assigned the Principal, is to use John Cardinal's TMG Utility to search for potential cases. (The TMG Utility is free, but is "donor ware," meaning John asks that you make a donation to his favorite charity if you find it useful.) Newly released version 7.3.3.2 or later is required for this test, so if you are using an earlier version you must first update to the latest version.

For this test, use the Search and Replace feature, as shown below, and then examine the resulting log:

As shown above, make the following settings:

• Set the "Field to change" drop-down to Event Sentence
• Enter in the "Find what" field:

\[R.*:

to search for the characters " [R " followed by one or more characters, followed by " : "

• Check the "Use Pattern Matching" box
• Check the "Log Only" box since we are only use the log to identify potential cases, not actually making any changes with the Utility

Click the "Find All" button, and you see a log like the following:

Each event with local Sentences is listed, showing for each case found the local Sentence, the Tag Type and date of the event, the name and Role of the subject of the Sentence, and if the subject is not a Principal, the name of the Principals. In the log, the Roles are identified by their internal number rather than their plain-language labels.

Events with potential issues are found by identifying Sentences in which the Subject is a Principal, and a [Rx:rolenumber] is found referring to the same Role number assigned to that Principal, as marked with red above. The Sentence actually requires correction only if there may be another person assigned that Role in the Tag, which is unlikely in the example shown since only one person is likely to be assigned the same Role as the Principal in a Birth Tag.

An alternate method, if you suspect you have used Variables like [RF:rolename], [RG:rolename], etc. in local Sentences for Principals to refer to that Principal in a particular Tag Type, the List of Events report with a Filter like the following (ver. 9.02 and later only) can help identify any such cases:

Note that this filter identifies Tags in which the Sentence for a Principal uses a Role Variable referring to that Principal's Role, but does not determine that the Role Variable is of the [Rx:rolename] type as opposed to the [R:rolename] type. So each case found would have to be examined to see if it uses an [Rx:rolename] Variable to refer to the Principal. Setting the Output Columns to something like the following may be helpful:

* (ver. 9.02 and later only)

With those wide field specifications output of the report as an Excel spreadsheet seems to work best.

Case 3: [Rx:rolename] Variables in Tag Memos for Principals

This issue arises when Variables like [RF:rolename], [RG:rolename], [RL:rolename], etc. are used in a Tag Memo, that Memo is referenced by the Sentence of a Principal, and the Variable refers to that Principal. The problem is that after the changes in the output of the Role Variables, if more than one person entered in the Tag is assigned that Role, a list of all of them will be output rather than just the name of the subject person.

There is no issue when:

• The Role is assigned to Witnesses, because for Witnesses all names have always been output. (Unless that was not the intended result, in which case the previous use has been producing unintended output.)
• The Variable refers to the other Principal, unless that person's Sentence also references the same Memo segment.
• The Role is never assigned to more than one person, either because by its nature, such as for "Bride" or "Groom," or because of the data entry practices of the user.

If you have Tags with this issue the solution is to change the [RF:rolename], etc. Variable to the corresponding subject Variable, such as [SF]. The difficulty is in identifying such cases. If you cannot recall such cases but suspect your Project may contain some, the following method may aid in the search.

You can use the List of Events report to create a list of Events with Memos which contain the Variables in question, then examine that report to identify any which refer to the subject person. A Filter such as the following may be useful:

If variations other than first name and given name may have been used to refer to the subject, lines should be added to the filter to search for them too. In Report Options, on the Output Columns tab, specify information to identify the Tags in question, and include as much of the Memo as possible to facilitate review of the Tags found. I have found the following arrangement of Output Columns useful:

* (ver. 9.02 and later only)

The report will allow you to see which Memos contain Variables of the type at issue, but you will then have to identify whether any refer to the Role(s) assigned the Principals by examining the Memos shown in the report. For example, you may see this Memo:

Examination of the Memo in this case shows that the Principals are referred to with the Variables [P1F] and [P2F], and that the [RF:rolename] variable refers to someone else, so this Memo is not an issue.

There is an alternate method, if you suspect you have used Variables like [RF:rolename], [RG:rolename], etc. in Memos of certain Tag Types, which are then used in the Sentences for Principals to refer to that Principal. You can use the List of Events report with a Filter like the following (ver. 9.02 and later only) can help identify any such cases:

This filter will identify cases where the Memo contains a Role Variable that refers to the same Role assigned to one or both of the Principals. It does not determine whether the Memo segment containing the Role Variable is used by the Sentence of the Principal with that Role. That has to be determined from examination of the Memo text and/or the Sentences of the Principals. The following arrangement of Output Columns (ver. 9.02 and later only) may be useful:

* (ver. 9.02 and later only)

With those wide field specifications output of the report as an Excel spreadsheet seems to work best.

Case 4: [R:rolename] Variables in Tag Memos for Principals or Witnesses

This issue arises when the [R:rolename] Variables is used in a Tag Memo, that Memo is referenced by the Sentence of a Principal or the Sentence of a Witness, and the Variable refers to that person. The problem is that after the changes in the output of the Role Variables, if more than one person entered in the Tag is assigned that Role, a list of all of them will be output rather than just the name of the subject person.

There is no issue when:

• The Variable refers to another person, unless that person's Sentence also references the same Memo segment.
• The Role is never assigned to more than one person, either because by its nature, such as for "Bride" or "Groom," or because of the data entry practices of the user.

If you have Tags with this issue the solution is to change the [R:rolename] Variable to the corresponding subject Variable, [S]. The difficulty is in identifying such cases. If you cannot recall such cases but suspect your Project may contain some, the following method may aid in the search.

You can use the List of Events report to create a list of Events with Memos which contain the Variables in question, then examine that report to identify any which refer to the subject person. A Filter such as the following may be useful:

In Report Options, on the Output Columns tab, specify information to identify the Tags in question, and include as much of the Memo as possible to facilitate review of the Tags found. I have found the following arrangement of Output Columns useful:

With those wide field specifications output of the report as an Excel spreadsheet seems to work best.

The report will allow you to see which Memo contain the [R:rolename] Variable, but will not identify which refer to the subject of the Sentence. That must be determined by examination of the Memos shown in the report, a strictly manual process.

Case 5: [R:rolename] Variables in Witness Memos

This issue arises when the [R:rolename] Variables is used in a Witness Memo, that Witness Memo is referenced by the Sentence of the Witness, and the Variable refers to that Witness. The problem is that after the changes in the output of the Role Variables, if more than one person entered in the Tag is assigned that Role, a list of all of them will be output rather than just the name of the subject person.

There is no issue when:

• The Variable refers to another person.
• The Role is never assigned to more than one person, either because by its nature or because of the data entry practices of the user.

If you have Tag Types with this issue the solution is to change the [R:rolename] Variable to the corresponding subject Variable, [S]. The difficulty is in identifying such cases. If you cannot recall such cases but suspect your Project may contain some, the following method may aid in the search.

You can use the List of Witnesses report to create a list of Events with Memos which contain the Variables in question, then examine that report to identify any which refer to the subject person. A Filter such as the following may be useful:

In Report Options, on the Output Columns tab, specify information to identify the Tags in question, and include as much of the Memo as possible to facilitate review of the Tags found. I have found the following arrangement of Output Columns useful:

With those wide field specifications output of the report as an Excel spreadsheet seems to work best.

The report will allow you to see which Witness Memo contain the [R:rolename] Variable, but will not identify which refer to that Witness. That must be determined by examination of the Witness Memos shown in the report, a strictly manual process.

Copyright 2000- by Terry Reigel