Change Name Parts

On this page: Description, Step by Step, Filters, Actions, User Variables, Field Labels, Rule Files, Example Rule Files

Description

Change Name Parts will change name parts (title, given name, surname, etc.) under the control of one or more filters and one or more actions.

Filters determine which names are changed. If more than one filter is supplied, the filters are anded together, meaning that the name must pass all the filters in order to be changed. The available filters support testing name part contents as well as the name style and the tag type.

Actions determine how the names are changed. The available actions support adding or deleting prefixes, adding or deleting suffixes, setting the entire contents of a name part, changing the name style or changing the tag type.

Both filters and actions use the standard name part labels.

Step by Step

1. Choose Change Name Parts under Names in the function tree.
2. Specify the filters and actions by clicking [Set Rules...] to open the Rules Editor.
3. Set the Match case checkbox if you want the filter terms to be case sensitive. When Match case is checked, "MIXED" does not equal "Mixed". When Match case is not checked, they are equal. The default is unchecked.
4. Set the Show All Name Fields checkbox if you want the log to show all the name fields in sequence rather than using the associated Name Style to format the log entry. This is useful if you are changing one or more subfields that do not display such as the SortGiven or SortSurname fields.
5. Set the Flag Filter, if desired. TMG Utility will only change names for people who pass the filter.
6. Click the [Change Name Parts] button.
7. TMG Utility will prompt for the literal values if the rule set includes user variables.

Filters

The sequence of filters is important only in that the processing will be faster if the most restrictive filters are at the top of the list.

Actions

You can combine actions to change multiple parts, etc. The sequence of actions is important only if you perform two or more actions on the same part.

When an action term modifies the Given or Surname field, you will usually want to modify the associated sort field, either SortGiven or SortSurname.

User Variables

Variables allow the creation of general purpose rules; the value of a variable is set via a prompt when you click the [Change Name Parts] button, not when you define the rules. You can include variables in any literal text field used by filters or actions.

User variables work the same way in all of the "Change <something> Parts" features including Change Name Parts, Change Citation Parts, and Change Place Parts. The description on this page applies to all those features.

Variables are entered as follows: "[Vn:prompt]" where

• "[V" is a literal string that starts a variable reference.
• "n" is a number from 1 to 9.
• ":" is an optional prompt delimeter.
• "prompt" is an optional prompt that TMG Utility uses when it prompts for the value of the variable.
• "]" is a literal character that ends the variable reference.

If you use the same value more than once in a rule set, and there's a possibility that in the future you'll want to use the same rules with different value, it's a good idea to use a variable to define the value and save the rule set to a file for later use.

TMG Utility will only prompt once for a variable, so you only have to key the "prompt" part of the variable reference once. For example, if you use [V1:Surname?] and in a subsequent filter or action you use [V1], both variable references will be replaced by the same value: whatever is keyed in response to the "Surname?" prompt.

If you click "Cancel" when prompted for a value, TMG Utility will not perform the processing defined by the action rules.

If you want a space (or other special character) before or after the variable text, but whether the space is necessary varies according to the filter or action where it is used, key the space as a literal and do not key the space when prompted for the variable value. See the "Move to PreSurname.u5rn" entry in the Example Rule Files section.

You can not nest user variables. You can put multiple variable references in a literal field, in any sequence.

TMG Utility saves the text you enter when prompted for the value of a user variable. If you rerun the same set of rules, the default value for each user variable will be set to the previous value. You can accept the previous value by clicking [OK] or modify the value before clicking [OK]. This helps when executing the rules with Log Only unchecked after doing a test run with Log Only checked by making it easy to ensure the real run mimics the test run without any inadvertent differences.

If you open the Rule Editor and press [OK] to close it, even if you don't make any changes, TMG Utility discards any saved values. The prompt values are not saved across sessions, so if you close TMG Utility and then restart it later, the default values will be empty.

Here is a set of rules that includes variable references.

Field Labels

You can reference the value of another field via a Field Label in any literal text value used by filters or actions. Field Label references support the creation of general purpose rules.

The Change Name Parts feature supports the following Field Labels only. If you use custom styles or country-specific versions of TMG that do not use the following labels by default, choose a Field Label from the list below based on the sequence # that matches your Field Label.

The [PRIMARYGIVEN] and [PRIMARYSURNAME] field labels are marked with * because they are different from the other field labels. They do not refer to fields in the current name. They refer to values in the primary name for the current person. The primary values are loaded prior to any changes to names for the current person, so if your Action rules modify primary names, these field values will be the "before" values not the "after" values.

Rule Files (.u5rn)

You can save and load rule files using the Rules Editor. The ".u5rn" files look like text files, but they include invisible characters embedded in the text. Don't change them with a text editor such as Notepad or TextPad. Change them using the Rules Editor.

Example Rule Files

There are a few example rule files in the Rules folder supplied with TMG Utility that demonstrate the feature and actually produce results you might want.

Change SortSurname.u5rn

Changes the SortSurname field when the Surname field is equal to a particular value. Use this example as a base when you want to assign a different SortSurname for specific names in your project. This method--changing the SortSurname for specific Surnames--is an alternative to using Add Standard Name. In this case, you don't add an extra name, you change the SortSurname field to match the expected or standard spelling of the surname.

This rule set uses two user variables: [V1:Surname?] and [V2:SortSurname?]. When prompted for "Surname?", key the Surname of the names for which you want to set a different SortSurname. When prompted for "SortSurname?", key the new SortSurname to be assigned.

Move to PreSurname.u5rn

This rule set moves a variable prefix from the Surname field to the PreSurname field. When prompted for "Surname Prefix?" key "de", "van", or some other prefix that you want to move from the Surname field to the PreSurname field.

The rules include an action to change the Name Style on the assumption that the existing name style does not show the PreSurname field. The name of the style will probably not match a name style in your project. Click on the Change Name Style term, then select the appropriate name style from the pull-down menu. The click [Update Action] to save the term change.

Move Maiden from Suffix to Other.u5rn

Moves the Suffix data to the OtherName field in Name-Marr tags when the suffix includes a specific leader and trailer in the Suffix field. This could be a useful tool for people who have put a woman's maiden name in the Suffix field of Name-Marr tags but who now want to use the OtherName field rather than the Suffix.