Editing TEI files

****** DRAFT ******

The manuscript descriptions are encoded using a customized TEI schema and stored in repositories (one for each catalogue) on GitHub hosting service.

Setting up GitHub

1. Go to https://github.com and sign up for a GitHub account.
2. Send a request that the username you have chosen be able to modify TEI files for your catalogue. This might be something you send to the organizer of your catalogue, or directly to your contact at the Bodleian.
3. Go to https://desktop.github.com, download and run the installer.
4. Sign in to GitHub in the desktop client with the account you just created.
5. Click the Clone a repository button.
6. Select the option that corresponds to your catalogue name and ends with "-mss".
7. Choose a location on your PC (on Windows it must be on local or network drive that has been assigned to a letter) as the Local Path.
8. Click Clone.

You now have a copy of everything you need to get started, including the latest versions of all the TEI files.

Editing TEI manuscript descriptions

1. Find the folder you specified as the local path when cloning.
2. The TEI XML files are kept in a subfolder called 'collections'. This must not be renamed or moved.
3. You can edit the TEI XML files, using Oxygen or another editor, saving as you go along. Organize the collections folder however you wish, creating subfolders as needed. You can delete and create new files. Individual TEI XML files can be named however best suits your collections, but ensure that:
   • Underscores are used instead of spaces in filenames.
   • Only keep one file for each manuscript description in the collections folder. Do not create backup copies or maintain two versions in two files.
   • Each manuscript description must be give a unique identifier in an xml-id attribute on the root TEI element within the TEI XML file. This will be used to create the URL of the manuscript on the web site. To ensure that this is unique it might be a good idea to maintain a spreadsheet to keep track of identifiers, shared by everyone who works on your catalogue.
4. Keep the GitHub desktop client open while editing. The files you modify will automatically appear in the Changes tab. It will also check periodically for other people's changes, and if it finds any a Pull origin button will appear at the top of the window to enable you to download them.
5. When you have completed a specific task (such as adding a new manuscript description, or searching and replacing to fix a misspelling across all existing ones), you should commit. This stores the state of all the files, labelled so you can easily revert back to that point in the future. To commit:
   1. Ensure all the files you want to include are selected in the Changes tab, deselecting any you may have been working on for some other reason, or which aren’t ready.
   2. Enter a summary (something short, like the subject if you were sending an email to someone about what you've done.)
   3. Optionally, enter a description (typically a sentence or two expanding on the summary.)
   4. Click Commit to master.

Validating against the schema

TODO

Making your changes available others and visible on the web site

The steps documented above only keep track of your work on your local PC. Your changes still have not been made available to anyone else. This is an extra step, which you should do as frequently as possible, to avoid making conflicting changes to the same files. But it will also make your changes available to be viewed on GitHub, and ready to be updated on the web site, so shouldn't be done if any of the commits you have made include files not ready for display to visitors.

1. When you are ready to share your changes, click Push origin.
2. This uploads the files you have changed to GitHub. Most of the time, this will simply report back that it has succeeded. But, if someone else has been editing some of the same files, you may be told there is a conflict, see below.
3. Pushing also updates the central repository's history log with the commits you have made, and the summary messages you attached to them. Therefore it is not necessary to inform the person who is responsible for updating the web site (although, if you have fixed something important, you can email them directly to ask them to run the processing scripts to update the web site immediately.)

Resolving conflicts

If you ever edit the same TEI XML file at roughly the same time another person, you may experience what are called "conflicts". This will happen either if you click the Pull origin button to get other people changes, or when you push yours to make them available.

1. The GitHub desktop client error message will display an error, telling you either to "commit your changes or stash them before you merge" or "resolve the conflicts and commit the changes". The former is if you haven't committed your changes yet, so do so now then click the Pull origin button again.
2. It will attempt to merge the two sets of changes, but the result is likely to not be valid according to the schema.
3. If you are sure your changes are correct, and the other person's are superseded by yours, you can right-click on the file in the Changes tab and select Discard Changes....
4. Otherwise, open the file in Oxygen and edit it, so that both changes are incorporated. Also remove the lines of text added by GitHub to point of the differences.
5. Ensure it validates, and save it.
6. Then, in the GitHub desktop client, enter a Summary of "Fixing merge conflict", and click Commit