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:

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 changes to the <id> element, paste this into the file: <old-ids><old-id> </old-id></old-ids>. Paste the original ID into this file (just the text, not the <id> 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; uncheck the checkbox "Update references..." and select the Rename button.)
6. Validate the file to ensure all schema checks pass.
7. Select Upload current file to history.state.gov to upload the file to the public website.
8. Return to the original file in oXygen. Select Delete current file from history.state.gov to remove the old file.
9. Commit the changes with GitHub Desktop.