Person names and IDs

Basic Principles

• Every person in the POCOM database has a name and an ID
• We endeavor to capture the most complete form of a name available, expanding all initials where the full name can be found and using given names instead of nicknames
• We use tags to distinguish between parts of a name: surname, given name (forename), and generational names (e.g., "Jr.", "III")
• The ID is derived from the name, according to the following simple rules:
  • Order: Last name + Given name + Generation name
  • Transformation: 1. Remove punctuation 2. Lower case 3. Replace space with hyphen.

Example

Taken from https://history.state.gov/departmenthistory/people/barnes-harry-george-jr, source at https://github.com/HistoryAtState/pocom/blob/master/people/b/barnes-harry-george-jr.xml.

<person>
    <id>barnes-harry-george-jr</id>
    <persName>
        <surname>Barnes</surname>
        <forename>Harry George</forename>
        <genName>Jr.</genName>
        <altname>Harry G. Barnes, Jr.</altname>
    </persName>
    [...]
</person>

Notice:

• The name elements are grouped into the <persName> element: <surname>, <forename>, and <genName>.
• Alternate, common renderings of the name may be captured in <altname>.
• The filename is derived from the <id>: barnes-harry-george-jr.xml.
• The file is stored in the folder of the first letter of the surname: people/b/barnes-harry-george-jr.xml

Fixing errors

When an error is discovered in a person name, or a more complete form of a name is discovered, we update both the name and the ID. Updating the <persName> elements is straightforward—just change the text—but changing the person's ID is somewhat cumbersome. The procedure is as follows—please follow the order exactly:

1. Do not directly change the source file. Instead, make a copy and make your changes to the new file. To make a copy, find the original file in the oXygen Project pane. Right-click on it file, and select Copy. Right-click on it again, and select Paste. A copy of the file will appear beneath the original, with - Copy appended to the filename. Open the copy in oXygen.

2. Make any necessary changes to the <persName> elements.

3. Before making any changes to the <id> element, paste this into the file, just beneath the <id> element:

    <old-ids>
        <old-id></old-id>
    </old-ids>
   

   Paste the original ID into the new <old-id> element (that is, just the ID text, not the <id> open and close tags).

4. Now change the <id> element to reflect the new name.

5. Change the filename of the copied file to match the new ID, by right-clicking on the copied file in the Project pane, selecting Rename, entering the new filename into the Project pane, and hitting return. oXygen will present a dialog window; be sure to uncheck the Update references... checkbox before selecting the Rename button.

6. Validate the file to ensure all schema checks pass.

7. Update all references to the old ID to match the new ID. In the Project pane, right-click on the pocom folder and select Find/Replace in File(s). Enter the old ID in the Text to find field, the new ID in the Replace with field, make sure the Make backup files checkbox is unchecked, and select the Replace All button. In the following dialog that appears, select Preview, which will let you review all of the changes to ensure there are no false positives. When you're sure the changes are all correct, select OK to complete the replace operation.

8. Open all changed files (double-clicking on them in GitHub Desktop), and select Upload current file to history.state.gov to upload all changed files to the public website.

9. Return to the original person file in oXygen. Select Delete current file from history.state.gov to remove the original person file from history.state.gov.

10. Delete the original person file on disk by right clicking on it in the Project Pane and selecting Remove from Disk.

11. Commit the changes to the POCOM GitHub repository using GitHub Desktop.