Change Citation Parts

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

Description

Change Citation Parts will change citations parts (source number, citation detail, citation memo, citation reference, split citation detail segments, and surety values) under the control of one or more filters and one or more actions.

Filters determine which citations are changed. If more than one filter is supplied, the filters are anded together, meaning that the citation must pass all the filters in order to be changed. The available filters support testing the text fields in the citation, the source number, the source title, the source abbreviation, surety fields, the segments in a split citation detail field, and the number of segments.

Actions determine how the citations are changed. The available actions support adding or deleting prefixes, adding or deleting suffixes, setting the entire value of a text field, or replacing selected text within a text field.

Note that you can filter the citations based on the source title or source abbreviation, but you cannot change the source title or source abbreviation.

Please read the Surety Notes section below before attempting to write rules that change one or more of the citation surety fields.

Step by Step

1. Choose Change Citation Parts under Citations 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 Prompt before each change checkbox if you want to be prompted to approve all changes. When prompted, you have the option to accept the change as is, modify the citation text, or skip the change entirely.
5. Click the [Change Citation Parts] button.
6. TMG Utility will prompt for the literal values if the rule set includes user variables.

Surety Notes

Some of the Action rules described below can be used to generate invalid values for surety fields. Change Citation Parts does not evaluate the Action logic prior to executing the actions, but it validates the surety value as the last step before making the final assignment. If the surety value is not one of the acceptable characters (hyphen, space, or the digits zero through three), it rejects the change and issues an error message.

Surety values are truncated during processing and only the first character in a multicharacter value will be retained. If your rules produce a surety value that is two or more characters long, only the first character will be retained.

You may use a shortcut to test for a combination of surety values. The Combined Surety filter field contains the individual surety values concatenated together in the usual TMG 12DPM sequence. Blank surety values are changed to periods in the Combined Surety value; periods are easier to see and count than spaces. The value "1...." will match a citation with P1 Surety set to 1 and all other sureties blank.

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. The sequence of actions is important only if you perform two or more actions on the same part.

The prepend operator inserts the given text at the beginning of a text field.

The delete prefix operator deletes the given text if it occurs at the beginning of a text field.

The set to operator sets the value of a field to the given text. For the Source Number field, the input value must be a number.

The append operator adds the given text at the end of a text field.

The delete suffix operator deletes the given text if it occurs at the end of a text field.

The replace action can be used to modify the contents of a text field. You specify a target value and a replacement value, and the target value is replaced by the replacement value everywhere it appears in the given text field.

The replace pattern action can be used to modify the contents of a text field. You specify a target value and a replacement value, and the target value is replaced by the replacement value everywhere it appears in the given text field. The target value is a regular expression.

Regular expressions are a powerful matching facility that allow you to search for patterns of text rather than for literal text values. If you are not familiar with regular expressions, you may want to consider them as a means to add wildcard characters to the target. Regular expressions are described for the Find and Replace feature. The replacement value can refer to text found in the input field; see the Variable Replacement Strings section on the Find and Replace Help page.

The syntax for user variables conflicts with some regular expressions. You will have difficulty if you try to use a character class expression that begins with "v", as in "[v ...]". Put the "v" elsewhere in the character class to avoid the conflict.

The copy operator can be used to copy the value of one field to another field.

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 Citation 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 Citation Parts, Change Place Parts, and Change Name Parts. See the description on the Change Name Parts page.

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 Citation Parts feature supports the following Field Labels only.

Rule Files (.u5rc)

You can save and load rule files using the Rules Editor. The ".u5rc" 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.