Nesting Manuscript Part Records into a Composite File

---

Title: Instructions for Nesting Manuscript Part Records into a Composite File Author: William L. Potter Date: 2021-12-07

Create Composite Manuscript Records from Manuscript Parts

Several of our manuscript records consist of multiple tei:msPart components nested within a composite tei:msDesc element. Each ms part receives a unique URI, and the composite receives its own URI. In current practice, XML records are created for each manuscript part. These records are then post-proecessed and edited as individual files before being automatically nested via XQuery script. This page guides you through processing, editing, and nesting ms part records into a composite TEI XML file for the full manuscript with tei:msPart elements for each ms part.

Creating, Post-Processing, and Editing Manuscript Part Records

Records for manuscript parts are created and post-processed following the identical procedures as records for full/simple manuscripts. (An overview of creation procedures is forthcoming). For post-processing, follow the instructions here.

Manuscript part records, once they have been post-processed, are stored separately until all the various parts of a given composite manuscript have been drafted and processed. In current practice, these are stored in /data/4_to_be_checked/need-ms-parts/. Once all parts of a given manuscript are ready for editing, follow these steps:

1. Create a folder in /data/5_finalized/ms-parts/ named based on the URI of the overall manuscript, e.g. /data/5_finalized/ms-parts/58/
2. Move the XML files of the ms parts into the created folder
3. Commit these changes
4. Edit each XML file as usual. Commit changes either file-by-file or after all files of a given composite ms have been edited

Once all the ms parts have been edited, they are ready to be nested as tei:msPart elements within a composite XML file.

Merging Manuscript Parts Records into a Composite File

The process of merging edited manuscript part records into a composite file is accomplished automatically via an XQuery script. Provided the above process has been followed, the subsequent steps should be executed:

1. Open the /parameters/config-msParts.xml files and update the following settings
   • xpath: /config/fileOrConsole. "file" writes to disk; "console" returns to the BaseX console for debugging and testing. This should usually be set to "file".
   • xpath: /config/outputFileDirectory. Use a relative path for where you want to store the nested record, e.g. /data/5_finalized/.
   • xpath: /config/manuscriptLevelMetadata/pathToMsPartsFolder. Use a relative path for where the XML files for each ms part are stored, e.g. /data/5_finalized/ms-parts/58/.
   • xpath: /config/manuscriptLevelMetadata/recordTitle. Contains the text node of the record's //titleStmt/title[@level="a"], e.g. "BL Add MS 12171".
   • xpath: /config/manuscriptLevelMetadata/uriValue. Contains the local name (numerical value only) of the URI for the composite ms record, e.g. "58".
   • The /config/manuscriptLevelMetadata/country, settlement, repository, collection should only rarely change.
   • xpath: /config/manuscriptLevelMetadata/shelfMark. Contains the shelf mark designation for the composite ms, e.g. "Add MS 12171".

Within the /config/msPartFiles element you can specify the TEI files or msPart elements to include in the composite file as ms parts. Each ms part is referenced in a part element within the msPartFiles node. These part elements should be in the order in which the composite file's msPart elements should appear—even if this order deviates from the order of the URI numbering system. Each part must have a <fileName> element that contains the file name, relative to the directory stored in the /config/manuscriptLevelMetadata/patToMsPartsFolder field. E.g., "1158.xml". If the whole file represents the manuscript part, the file name is sufficient.

However, if the manuscript part is contained within an msPart in the file identified by the fileName field,use an oldPartId element within the same part which references the @xml:id attribute of an msPart element within the file specified in the //fileName node. Example:

<part>
  <fileName>1158.xml</fileName>
  <oldPartId>Part4</oldPartId>
</part>

This example would create a part based on the data contained in and associated with (e.g., taxonomy values) the ms part in 1158.xml corresponding to //msPart[@xml:id = "Part4"].

To create a nested msPart within another msPart, simply create a <part> node within a <part> node and specify the fileName and optional oldPartId for the data you wish to nest as an msPart.

<part>
  <fileName>1158.xml</fileName>
  <oldPartId>Part4</oldPartId>
  <part>
    <fileName>1159.xml</fileName>
  </part>
</part>

Finally, since the first part, according to the new order, could be a fragment rather than a full TEI record (i.e., when the first part is pulled from an msPart element within another file, rather than the whole file), the /config/compositeMsFile element allows you to specify a full TEI record to use as the template. Note that the contributor information such as editor[@role="creator"] and respStmt elements will be included from this template record, so ensure that it does not contain extraneous data.

This system of declaring ms part sources should cover all permutations needed for creating composite manuscript files from component parts.

2. (Optional): In the file /parameters/config.xml you can change the /config/pathToIndexOfIdsToUpdate value to a directory where you want to store the index of updated xml:id attributes. These indices are used to propagate changed xml:ids to other data which reference them. This parameter should be changed only rarely and with caution.
3. Open BaseX and set the global option to preserve whitespace: set chop false
4. In BaseX, open /drivers/msParts-merge.xq and execute
5. The following conventions are currently employed on the Wright Decoder
   • Assign yourself in the "Who is primary?" column for the composite manuscript
   • Once the script has been executed, change the "state of encoding" for the composite manuscript to "Drafted and Edited" and the "Edited by whom and when" column to "Your Name, current-date"
   • Add "generated by script" (for the composite) or "nested by script" (for the ms parts) for each row in the "Editing questions and comments column"
6. Check the output and commit changes. In current practice, the ms part records are being edited as separate files before being merged (see above), so no further edits should be required before transferring the composite record to the app-data repo.
7. Commit the changes to the id updates index separately. These can be stored indefinitely as a future script (perhaps run once at the end of the project) will go through and propagate the id changes to any references thereto.

Once the composite record has been created, it can be moved to the Srophe data repository. It should also be moved from /data/5_finalized to /data/5_finalized/TransferredToDev. Commits should be made on both repositories. Note: at present, the manuscript repository on the Srophe data repository only exists on the dev branch.