Schema and Documentation for the Colonial Despatches of Vancouver Island and British Columbia
language: en

The Colonial Despatches of Vancouver Island and British Columbia
Schema, documentation and guidelines

Ireland Good
Nathaniel Hayes
Martin Holmes
Gord Lyall
Lily Maase
Kim Shortreed
2019

The Colonial Despatches of Vancouver Island and British Columbia

Welcome to the Colonial Despatches project. This document provides detailed guidelines for editors, programmers, maintainers and research assistants working on the project.

Using the Subversion repository

We keep all our XML file and related documents in a Subversion Repository. This is a version-control system that ensures that every version of every file can be retrieved if necessary, and prevents one person from inadvertently overwriting changes to a file made by someone else.

Subversion runs on one of our HCMC servers. In order to use it, you will need to install a Subversion client on your computer, and also learn a couple of simple command-line commands. Subversion is usually abbreviated to svn.

Installing a Subversion client

How you will do this depends on which operating system you are using.

Windows

Obtain a command-line client from CollabNet (http://www.open.collab.net/downloads/subversion/). Registration is required to download the program, but there is no cost. Make sure to download the correct version; there are versions for 32-bit and 64-bit Windows. Once the program is downloaded, install it by double-clicking the downloaded installer and following its instructions.

Macintosh

Installing svn on Mac has become slightly complicated recently because Apple have removed it from their XCode toolset. We now have to install it using Homebrew, which is a package manager for the Mac. Here are the steps:

- Go to the Homebrew home page.
- Copy the long line of code under ‘Install Homebrew’ to the clipboard.
- Open a terminal.
- Paste that code into the terminal.
- Press return.
- Supply your password when required.

The Homebrew install process takes a little while. When it completes, go back to the terminal and type this:

brew install svn

When svn is installed, test it by typing in the terminal:

svn --version

You should see lots of mysterious information, but the first thing should be the svn version number which is now installed on your machine.

Linux

Subversion is installed as part of a regular desktop on most Linux distributions.

If you do not have subversion on your Linux:

- Open a terminal.
- Type: sudo apt-get install subversion
- Press return and answer "y" to questions about space.

Checking out the repository for the first time

Once your subversion client is installed, the first thing we need to do is to check out the repository. To do this, you need to open a terminal window:

- On Windows, click on the Start menu and type cmd into the search box.
- On a Mac, select Terminal from the Utilities folder in Applications.
- On Linux, press Control + Alt + T.

Now we'll check that svn is installed and working. Type svn checkout and press return. If the terminal responses that there are Not enough arguments provided, then svn is working OK.

Now we'll create a directory for our project files:

mkdir coldesp

And now we've created that directory, we'll navigate into it:

cd coldesp

And now we'll check out the files from the repository into our directory. Make sure you don't forget the space and period at the end of this command:

svn checkout https://hcmc.uvic.ca/svn/coldesp/trunk .

Don't forget the final period.

Using SVN in your daily work

These are the basic rules when you're working with svn:

Before you start work, update your local files:

- Open a terminal
- cd coldesp
- svn update

You can leave the terminal open while you work. Then, when you're ready to commit your changes:

- svn update (again, just in case anything else has been committed by someone else)
- svn commit -m "A message explaining the changes you have made" *Note: the very first time you commit, SVN might ask for a password. If it does, hit enter. Then it will ask for your netlink id and then netlink password which you can give and hit enter.

That's basically it. If you see any warnings or error messages from svn, check that you're in the right folder in your terminal. You may also see error messages if two people have been editing the same file at the same time, and Subversion needs you to make a decision about whose changes should be kept.

Tips for using the terminal

Finding out where you are right now:

pwd

Moving up the tree one level:

cd ../

List files in a folder:

ls

List files in a folder with full information:

ls -al

XML terminology

For an introduction to XML please see the w3schools tutorial here. The two main components of XML that you should know are “elements” and “attributes” .

Working with Oxygen

Your encoding work will all be done in the Oxygen XML Editor. When you install Oxygen, there are lots of applications that come with it: Oxygen Author, Oxygen Developer, Compare Files, Compare Directories and others. But the one you want to work with is always Oxygen XML Editor, which has the blue icon with the red cross on it. Here's how to get started:

- Open the Oxygen XML Editor.
- Click on Project / Open Project…
- Navigate to the coldesp folder in your home directory.
- Choose the file coldesp.xpr.

You should see a tree of folders and files down the left of your Oxygen editor. This includes all the files in the project. You can ignore most of them. The folder that matters is the trunk/xml folder, where all the TEI files and schemas are kept.

Tip: You will want to enable line wrap for editing purposes:

- Open "Options" > "Preferences…"
- Select the arrows to open both "Editor" and "Edit Modes"
- Then highlight "Text" and in the right side box you can select "line wrap" (see below).

Validate your files before upload

This is important: always validate any and all XML files in Oxygen before uploading them to the repository in Terminal/SVN. Get into the habit of saving your files often (Ctrl + S on your keyboard), and validating often (Ctrl + Shift + V on your keyboard).

To validate the file upon which you are currently working, use the following keyboard command: Ctrl + Shift + V. Alternatively, click on the validate button in Oxygen's toolbar. The button looks like this:

To validate multiple files, (1) open Oxygen's built-in file browser, (2) select the folder you want, and (3) select Validate. Here's a screenshot of the process:

Oxygen code templates

Our Oxygen project file has a number of useful keyboard shortcuts built into it, which you can use to speed up your encoding. Generally speaking, to use these, you select some text in the editor, then press the keystroke shortcut shown in the table below. The table uses the following key names:

M1	represents the Command key on MacOS X, and the Ctrl key on other platforms.
M2	represents the Shift key.
M3	represents the Option key on MacOS X, and the Alt key on other platforms.
M4	represents the Ctrl key on MacOS X, and is undefined on other platforms.

Name	Description	Result	Keystroke
ColDesp: Curly apostrophe	Curly apostrophe	“${caret}${selection}”	M1 M3 M2 QUOTE
ColDesp: Name tag	tag for names of people	<name key="${caret}">${selection}</name>	M1 M3 N
ColDesp: New person	Mark-up for new person entry in personography	<person xml:id="${caret}"><!-- added by INITIALS; 0000-00-00 --><persName type="unavailable"> <surname></surname>, <forename></forename></persName> <!--<birth when="1111-11-11"></birth>--> <!--<death when="1111-11-11"></death>--> <note> <p></p> <p><listBibl> <bibl>1. </bibl> </listBibl></p> </note> </person>	M1 M3 1
ColDesp: New place	Mark-up for a new place entry in places	<place xml:id="${caret}"><!-- Added by INITIALS; 0000-00-00 --> <placeName>NAME</placeName> <location type="path"><geo></geo></location> <desc></desc> <desc> <listBibl> <bibl>1. </bibl> </listBibl> </desc> <!-- <name type="place" key="KEY">NAME</name> --> </place>	M1 M3 3
ColDesp: New vessel	Mark-up for a new vessel entry in vessels	<item xml:id="${caret}"><!-- Added by INITIALS; 0000-00-00 --> <label><name type="vessel" key="KEY">VESSEL NAME</name></label> <p></p> </item>	M1 M3 2
ColDesp: Place tag	tag for a place	<name type="place" key="${caret}">${selection}</name>	M1 M3 P
ColDesp: q tag	wrap selected text in a q tag	<q>${selection}</q>	M1 M3 Q
ColDesp: superscript tag	Superscript for suffixes such as "st" and "th"	<hi style="vertical-align: super; font-size: 80%;">${selection}${caret}</hi>	M1 M3 S
ColDesp: Vessel tag	tag for a vessel	<name type="vessel" key="${caret}">${selection}</name>	M1 M3 V
ColDesp: £ sign	"£" sign	£	M1 M3 4

Prepare images for the Colonial Despatches website

Background

We need to produce three sizes of each image for all of the pages in the online collection: a thumbnail (60px wide), a medium-sized one (800px wide), and a full-sized image (size varies). Also the images we receive, usually shot as two-page spreads, get split and saved as either recto or verso .

Readers can view these images in a couple of ways. The thumbnail images appear to the right of the digital versions, or transcriptions, of the letter.

On the website, we place the images of the actual letters next to their corresponding content in the digital transcriptions, so that readers can easily compare our transcriptions with the originals.

If readers click on the thumbnail image they will be linked to the second way to view the images, in the “MS images” browser.

The MS (manuscript) images browser has basic features for now, but it allows readers to jump around in the image collection, and then dive back into the digital transcription of a given letter. Finally, on the home page of the website, we provide readers with an index page for all of the manuscript images.

Where we get our images

“Images” refers to photographs of the original letters, which we receive in several forms. Typically, Chris Petter (now retired), at UVic's McPherson Library, ordered digital images from places such as Library and Archives Canada (LAC), among other sources. These images arrive, on a portable hard drive, as digital scans of LAC's archival reels, or microfilm.

Typically, each frame of the reel captures two pages at once, as they are photographs of an open book that contains the despatches. We separate, crop, and when necessary, optimize the images, and then save them as either recto or verso, with an appropriate file name. On occasion, we have used the library’s film scanner to produce our own scans, which you can read about below.

Step by step: prepare images for the website

Please read through all of these steps and the FAQ section below before you begin tackle this process.

After you have read everything in this section, come back and refer to the step-by-step portion as you proceed. These steps will direct you on how to find appropriate images, place copies on your desktop, process the images, and create multiple sizes of each image.

- Find a reel of images to process from the Coldesp Image Inventory. To find a reel that requires processing, review the “images produced” column and look for a cell with a value of zero. In the “notes” column write your initials and the date you started processing the images.
- On your desktop, create a new folder called “RawImages” and a folder with the name of the collection you are working on. The name of the collection can be found in the image inventory consisting of the “group,” “series,” and “volume” information. (See below)
- If we were to process the first row (row 2) of the images the folder name would be co_305_01. NOTE: all lower case and there are NO spaces, use underscores instead and two digits for the volume number, so “01” NOT “1.”
- Inside your collection folder create another folder called “jpg_full_size.” This is the folder that you will place your processed images in.
- So to recap: you should now have on your desktop a “RawImages” folder and a collections folder named something like “co_305_01” which has a “jpg_full_size” folder inside of it. Now we need to get your raw images…
- Raw images are found on the “sftp” server at sftp://nfs.hcmc.uvic.ca/home1t/coldesp/archive. If you don’t have permission to access this directory, please talk to the HCMC staff or ask the Despatches team to retrieve the needed files for you. You will find the correct reel where your raw images are located by looking at the “reel-folder” column in the images inventory. Often the collection will start somewhere in the middle of a reel, if there’s no note about what the file name of the image is that starts the collection in the image inventory you will have to just scan the contents of the reel until you find the first page.
- Copy the images to your machine by placing them in your “RawImages” folder. NOTE: sometimes a collection is recorded across two reels, if this is the case then please make copies of the raw images from both reels.
- Open Shotwell and select File > Import from folder. Select your “RawImages” folder and “import in place.”
- Oddly, Shotwell presents images counterintuitively to most image manipulation software. Your first image will appear at the bottom-right corner (see below). And you will move from right to left heading up as you work through the images. Not sure why this is, but some things are better left a mystery.
- Typically, you will want to straighten the image, crop, and possibly adjust the saturation or contrast. You’ll find your image adjustment tools at the bottom of the Shotwell window. Once you’ve completed your adjustments, it’s time to export your image.
- You’ll be exporting your image to your “jpg_full_size” folder, in the collections folder. To export your image go to File > Export. Be sure to give your file the correct name. NOTE: you may see a pop-up that asks you to accept all current size and quality settings. Click OK to confirm the settings.
- Don’t forget to save backups of your work frequently. For more information see Should I make backups of my processed images?
- For details on cropping please see the FAQ below. For proper file naming see the rename section.

FAQ on preparing images with Shotwell

What if I want to undo my changes?

Press “Ctrl”+“z” (undo last change) to revert any unwanted changes. This shortcut works for Shotwell, the file-saving dialogue, and most software programs.

How do I know what to trim and what to keep?

As a general rule, we try to keep any features that might be of interest to archivists, scholars, or other users of the site. For example, in the image below we keep the tab and the spectral archivist's finger:

However, we always crop away the little slip of paper, called the archival-data slip, next to the page image. It’s redundant, as our digital records incorporate this information already.

You will find special cases, where it’s unclear what to trim or keep. As always, consult the Despatches team if you are uncertain.

How do I know what to rename my files?

Our image filenames derive from the front page of the archival images, which appear in every collection in some form or another, plus the addition of enough decimal places to accommodate even the largest image collection within a given repository. Here is an example of the first page from a collection, with fancy graphics:

As you might guess from the example above, the file name for the next image, the “back” of the page or the verso, would be co_305_01_00001v.jpg. The number then changes with the next recto image (“front”), which would be co_305_01_00002r.jpg, followed by co_305_01_00002v.jpg, and so on.

Is there an efficient way to name the files?

The following answer concerns the “Export…” dialogue in Shotwell. To make this process faster, for all proceeding images, click on one of the existing renamed images in the “collection” folder. Your new filename will inherit whatever filename you click on. Then, all you have to do is change the number(s) or letters (the “v” or “r”).

Here are some more details on how this process works:

- After clicking “Export…” and navigating to your “collection” folder, you will find the first image named co_305_01_00001r.jpg.
- To rename your second image, click on co_305_01_00001r.jpg in the “collection” folder. The “filename” should now become co_305_01_00001r.jpg. Changing the letter “r” to “v” will rename the second image to co_305_01_00001v.jpg.
- To rename the third image, you have two options (depending on your preference):

- Select the first image name, co_305_01_00001r.jpg, and change the number “1” to “2.” Or…
- Select the second image, co_305_01_00001v.jpg, and change “1v” to “2r.”

Both options will give you the following result: co_305_01_00002r.jpg.

TIP: In the Shotwell export window make sure you’re viewing your “jpg_full_size” folder as a list and click the “modified” column to make the most recent file show at the top. That way when you are naming your next file you can click on the top file and either replace the “r” with a “v” or add a new number with an “r.” You’ll be creating hundreds of files, you don’t want to have to scroll to the bottom to name each file.

What happens to the filenames when I move beyond single digits?

The number of digits in the filenames eventually increases from single digits to double digits, to triple digits, etc. It’s important that you remember to take away one zero in the file name each time the number of digits increases as in the examples below:

- co_305_01_00001r.jpg
- co_305_01_00010r.jpg
- co_305_01_00100r.jpg
- co_305_01_01000r.jpg

What do I do with duplicates at the ends and beginnings of reels?

Problem: In the raw/archival image files, you encounter a “CONTINUED ON NEXT FILM” image, followed by a “CONTINUED FROM PREVIOUS FILM” image, followed by another archival record sheet, followed by a duplicate image from the previous reel.

Solution: Incorporate all but the duplicate image, as in the example below:

Note: the order of the recto/verso images can change from collection to collection. For example, the image prior to the “CONTINUED ON NEXT FILM” image could end on a verso. This would change the “CONTINUED ON NEXT FILM” image to an “r” and the “CONTINUED FROM PREVIOUS FILM” image to an “rx,” and the archival record sheet to a “v.” Easy peasy.

Should I include the “end of volume” slide?

Yes. This should be the last slide in every collection (nearly all collections contain this page). Straighten, crop, and name it as you would any other file. It doesn’t matter, either way, if this slide ends up being a recto or a verso.

Any tips for newbies?

Cropping images may seem like a simple and fast process, however it’s very easy to make mistakes, especially ones that may cost you more time to fix than it did to process the images in the first place. Here are some tips that may help you avoid making those mistakes, in no particular order:

- Take your time! If you rush, you may skip images, misname them, or process the same one twice.
- Take “brain breaks” as needed, or at least once per hour, as they curb mental fatigue. Check Facebook, tell a colleague a work-appropriate joke, drink some water, eat a snack, or go outside and verbally chastise first-year students.
- Before you crop an image, jump ahead one image to make sure it has no following duplicate.
- Use your keyboard’s arrow keys to navigate through images in Shotwell.
- Double-check your work frequently. At first, check every 10 to 20 images to make sure you (1) are happy with how they are cropped, and (2) that they are named properly. Compare your images with the raw image files to make sure that your images follow the correct order. If you screw up, say, image 30 of 300, then every image from 30 onwards will have to be renamed!

Should I make backups of my processed images?

Yes. This step is essential. Backups can be stored in several ways. Ideally, you should have your files in three locations: (1) on your work computer, (2) stored on the “Coldesp” server (see below), and (3) in another location, such as a datakey, or a non-Coldesp server, such as your private unix.uvic.ca account, which every UVic student gets by default.

To be able to backup your images on the Coldesp server, ask Martin to create a folder for you. Have him or another Despatches colleague show you how to access said folder with an FTP client of some kind. At the end of your shift, copy your “RawImages” folder into these backup locations. It goes without saying that the loss of hundreds of your hard-earned, processed images would, in a word, suck.

How do I handle recto/verso sequence problems?

Problem: In the archival images, you encounter a single-page image that disorders your naming sequence, whereby the proceeding image would become a recto, when it should be a verso.

Solution: Add an “x” to the end of the name of the single-page document. For example, if the file preceding the single-page document is named co_305_02_00096r.jpg, the out-of-sequence page becomes co_305_02_00096rx.jpg, and the following image would resume the sequence as co_305_02_00096v.jpg.

Sometimes, you will find very wonky sequence problems. Always consult your Despatches colleagues for help whenever you are not 100 per cent certain as to how to proceed.

Here’s an example of an archival placeholder that disrupts the recto/verso order:

Note: notice that the page numbers in the original document appear on the top-right corner of the recto pages (00641r and 00642r).

How do I double-check my work?

Once you’ve processed all the images in a given batch, and they’re all sitting there, smiling back at you from within the collections folder, you need to make sure that your collection is perfect. In any image viewer, browse through the whole collection folder, start to finish, and make sure everything is where it should be.

An easy way to do this is to use the page number stamps, usually located at the top-right of each recto page, as your guide.

Use these page stamp numbers to count from one to the final image in the collection. If you skip a number, or see the same number twice, then you have reason to investigate.

I screwed up the order of my images, now what?

Problem: you realize that you made a mistake in your image collection. For example, you accidentally added the same image, or images, twice. You then delete the copy or copies, and now your filename order is screwy. Now all the images after the deleted file(s) are one number ahead, and there’s hundreds of them to change…

Solution: KRename to the rescue!

KRename is a filename editor for Ubuntu (Linux). We have used KRename to excellent effect, though the processes involved can be rather complicated, and should not be attempted without guidance from someone in the know. Please seek technical support from a Despatches colleague, one who has used KRename before, prior to using this program.

Here are some KRename scripts we have used:

- [$1;12]###{13;1}r
- [$1;07]###{97;1}r
- [$1;5]30_#####{1;1}r
- [$1;5]32_#####{466;1}r
- [$1;6]_14_#####{185;1}r
- [$1;9]#####{10;1}r

If you’re uncomfortable with this process please contact the Despatches team. They’ll be more than happy to help you sort it out.

Am I slower than everyone else at this?

Probably not. We’d rather you go slow and steady than race along and make mistakes. At first, it might take you four hours to produce 40-50 images. With practise, your robot genes will kick in, and you’ll soon tickle the team record of over 200 images in a seven-hour shift.

Adding data to the inventory

Once you’ve processed all your images, please count the number of new images that you created and add that number to the “Images Produced” column in the Coldesp Image Inventory. Also, don’t forget to change your note from [initials, date] “started working” to your new date of completion and add “complete.”

Create three sizes of the images for the website using image resize script

We create three sizes of the images you prepared by running a short Bash script developed by the Despatches team.

- You’ll find the script on the SFTP server at sftp://nfs.hcmc.uvic.ca/home1t/coldesp. You need an FTP client to access this address (pre-installed on the HCMC Linux computers). For your PC you can use a freeware FTP client such as FileZilla. The script is called “image_resize.sh.” Make a copy and save it to your desktop (ideally beside your collection folder with a proper name, e.g. “co_305_01”).
- Make sure the script is executable. There are two ways to do this: a) right-click on the script, go to Properties > Permissions and toggle on “allow executing file as program”; or b) open a terminal window, make sure you are in the desktop (cd Desktop), and type: “chmod u+x image_resize.sh” (without the quotation marks), then hit enter. See the two examples below:
- To run the script use the terminal (once again make sure you are at your desktop). Type “./image_resize.sh” (no quotations) and hit enter.
- You’ll be prompted to confirm the name of your collections folder. Enter the name of the folder (no typos or the script won’t find the folder) and hit enter.
- Ta Dah! The script will have now made two more sets of your images. One size at 60 pixels called thumbnails and another at 800 pixels. These will all be inside your collections folder.

How to package and deliver your images for upload to the Despatches site

This section assumes that you have FTP access to the “coldesp” server, and that you have a folder on the “coldesp” server, which contains your current work. Martin is the chap who uploads all of the images to the website proper. FYI: all the images for the site are stored in “coldesp/www/jpg_scans,” which contains three folders, one for each size of image.

- By now, you should have three folders on your desktop, one for each size of image. Ensure that each of your three sizes of web-ready images are in separate folders, and named as follows: “jpg_full_size,” “jpg_800,” and “jpg_thumbnail.”
- Place your three folders into a single folder, which you should name in such a way that it would make sense to you, or someone else, later. For example, “co_6_27_web_ready_images” tells you everything you need to know. Here’s a picture to help you out with this whole process:
- Upload your folder full of images to your personal folder on the “coldesp” server.
- IMPORTANT: Once your pictures are uploaded, set the permissions to allow read/write access to the “group.” Be sure to set the permissions recursively (to all the files within all the folders).

- To set file permissions in Nautilus (Ubuntu’s default file browser), right-click on a folder, then navigate to “properties” > choose the “permissions” tab > and under the heading of “group,” set the “folder access” drop-down selector to “create and delete files”; then, under the same heading, set the “file access” drop-down menu to “read and write.” Finally, click on the “Apply Permissions to Enclosed Files” button to commit your changes.
- How to set permissions in Filezilla, should you use it instead.

- Make backups of your files in your prefered location(s).
- Email Martin to notify him that you have new images to upload to the site. As a courtesy, in your email tell him the “filepath” to the files. For example, “coldesp/yourfolder/co_6_27_web_ready_images.”

Digitize microfilm reels

Rarely, and to complete a given collection or year’s worth of images, we might have to digitize our own images from a microfilm reel. Chris Petter, the head archivist at the library (now retired), would order whatever microfilms we might need. The Microform Centre at UVic's McPherson library has a microfilm scanner, the features of which are too complex to address here, but if you ever have to scan microfilm, follow these general rules:

- Make your scans in greyscale, NOT black and white.
- Save your files as as 300 DPI JPEGs, as in “image.jpg.”
- Name your microfilm scans/images appropriate to their collection of origin. Talk to your Despatches colleagues about how to do this.
- Add your images to the “archive” folder (in the “coldesp” folder), and in the appropriate place. Again, consult your Despatches colleagues about how to do this, and for how to name the folder appropriately.

Markup or “tagging” guide

Introduction

This section provides details on how to markup, or tag, the various content in the XML files. We add to this section each time we encounter a novel problem, and agree on an appropriate solution. Some issues remain open, of course.

We also try to keep things in alphabetical order, by heading, to give this otherwise amorphous mass of words some sort of shape. Most of us use “Ctrl + f” on the keyboard, and then search for the term we want. This method is an easy way to jump around in this guide

Additions

According to the TEI guidelines, additions are “letters, words, or phrases inserted in the text by an author, scribe, annotator, or corrector.” You may see them in the despatches as words or phrases hovering above or below the regular text line, often with an “^” or “‸” inserted by the author to indicate its intended location.

Here’s the code to handle the floating or out-of-line text, using the example word “that”: <add place="above">that</add>

Note that the place attribute indicates the location of the inserted word or words relative to the main line of text. In the above case, the word “that” is inserted “above” the main line of text. You could use other placements as well, such as “bottom,” “margin,” “bottom opposite,” and so on. Here’s an example of each, still using the word “that”: <add place="bottom">that</add> <add place="margin">that</add> <add place="bottom opposite">that</add>

See Martin for guidance on all of this, or for more options for location attributes.

Here’s an example of a “subscript caret” (‸):

Add the following HTML code to the XML document, wherever you want the caret to appear (you can copy and paste from below): ‸

Add the caret code before or after the word, as it appears in the handwritten document.

In the case of the example image above, where the caret is before the added word “that,” the full code should look like this in your XML document:

<choice>
   <sic>‸<add place="above">that</add>
   </sic>
   <corr>that</corr>
</choice>

Note that the <choice> , <sic> , and <corr> tags are added in the above example. We add these tags so that we can choose to display the addition-word as either (1) part of the main line of text, our current default, or (2) as it is in the actual letter, floating away from the main text line.

A superscript caret (^) can be used as per usual in Oxygen.

Ampersands

XML views ampersands as pure evil! Fine, as code. So, if you have to use an “&” it will appear as invalid. You must use the following text instead wherever an ampersand appears: &amp;

Note: ampersands can sometimes appear in longer links. These instances must also be corrected so that your document is valid and the link isn’t broken.

<biblScope> and <pb> tags: for page beginnings, or page linking

We need a way to line up the XML files with the images of the pages they represent. Since the XML document often represents the content of many scanned pages, we need to show the online reader when a page change occurs in the digital, or online, text. We start the whole shebang with a <biblScope> tag, as this tag links the digital document to the first page of a given letter.

<biblScope> tags

This tag places the first page of a letter’s image at the beginning of the digital version. The code for the tag looks like this: <biblScope type="startPageImage" facs="folder of images here/individual image here">repeat individual image link here</biblScope>

Here’s a blank code example, which you can copy/paste into your XML document. Make sure you change all the necessary details so that the image points to the right place! <biblScope type="startPageImage" facs="co_?_?/co_?_?_00000r.jpg">co_?_?_00000r.jpg</biblScope>

Here’s what the whole thing looks like in an actual example. Note that the <biblScope> tag appears between the <date> and <series> tags as descendants of the <sourceDesc> .

<sourceDesc>
   <bibl>
      <idno type="repository">CO</idno>
      <idno type="coNumber">305</idno>
      <idno type="coVol">6</idno>
      <idno type="page">46</idno>
      <idno type="coRegistration">6875</idno>
      <idno type="received">received 23 July</idno>
      <idno type="despatchNo">3</idno>
      <date when="1855-05-16">1855</date>
      <biblScope type="startPageImage" facs="co_305_06_00047r.jpg">co_305_06_00047r.jpg</biblScope>
      <series>V.I.</series>
      <note>Transcribed from microfilm archives, marked up in Waterloo Script, then transformed into TEI P5 XML.</note>
   </bibl>
</sourceDesc>

<pb> tags

We use <pb> (page beginning) tags to indicate the beginning of a new page in the document. At the same time, we use the @facs attribute we link to the original image.

On the website, the page beginnings are indicated by the thumbnail images in the right margin. Users can click on the thumbnails and go to a larger, readable version (the 800px size) and click on the 800px image to see the full-sized version. So, really, what the following code does is decide where to place the thumbnail image relative to the digital text.

Below is the code for the <pb> tags. You can use this example as a blank template. <pb n="co_?_?/co_?_?_00000r.jpg"/>

Here’s an example of an actual <pb> tag in action! …is ready to receive and consider the Draft of such a Grant as the Company would desire to receive of lands belonging to the British<pb n="co_305_01/co_305_01_00052v.jpg"/> Crown…

In the above example, we can see that the last word on one page of this despatch was “British,” then we indicate that the page “breaks” with the <pb> tag, which is followed by the first word on the following page: “Crown.”

We can also see that the content within the <pb> tag breaks down as follows: <pb n="foldername here/fileneame here"/>

IMPORTANT: page beginning tags always refer to, or introduce, the following page. Also, It is a “self-closing” tag. There’s no need for a closed, or </pb>, tag.

<biblScope> and <pb> FAQ

How do I tag catchwords?

Catchwords appear in most correspondences longer than one page, including minutes. Catchwords indicate a change of page by repeating the final word on the page at the start of the following one.

Arguably, this system is better for loose sheet collections than page numbers, which could confuse recipients. Imagine if there were multiple letters in a given packet, each with its own page three, it could be difficult and slow to repair the order if they got mixed up. But, catchwords are unique to the content of each correspondence. So, all you need to do is match the words to match the page order.

Here’s the the XML version of the above example:

… of which Your Grace is far better able to judge, than I to represent; but I may add that there is much reason to fear that unless her Majesty’s Government <fw type="catchword" style="text-align: right;">authorise</fw>
                       <pb n="co_60_08/co_60_08_00020r.jpg"/> authorise me to take the initiation in this great work, the Country may be found with religious teachers supported by the…

And, here’s how the text will appear on the website:

Below is a catchword template: <fw type="catchword" style="text-align: right;">catchword here</fw>

Here are some catchword rules we’ve adopted over the years

- Catchwords always get placed before <pb> tags.
- Place the opening <fw> tag directly after the last word on the page, with no spaces:

- WRONG: Majesty's Government <fw type="catchword" style="text-align: right;">
- RIGHT: Majesty's Government<fw type="catchword" style="text-align: right;">

- Do not place spaces within the catchword tag:

- WRONG: <fw type="catchword" style="text-align: right;"> authorise </fw>
- RIGHT: <fw type="catchword" style="text-align: right;">authorise</fw>

- Leave no space between the closed </fw> tag and the <pb> tag:

- WRONG: authorise</fw> <pb n="co_60_08/co_60_08_00020r.jpg"/>
- RIGHT: authorise</fw> <pb n="co_60_08/co_60_08_00020r.jpg"/>

- Finally, and just to drive you crazier, you do leave a space, the one that occurs naturally in the text, after the <pb> tag:

- WRONG: <pb n="co_60_08/co_60_08_00020r.jpg"/>authorise
- RIGHT: <pb n="co_60_08/co_60_08_00020r.jpg"/> authorise

What if a catchword occurs right after the end of a paragraph?

Occasionally, a catchword will appear after the final paragraph on a given page, making the catchword the first word of the beginning of the paragraph on the following page. In all such instances, place <fw> tags (and the <pb> tag!) between the closing </p> tag and the opening <p> tag of the next paragraph, as in the following example from an actual XML document:

<p> … a toll on goods carried from <name type="place" key="new_westminster">New Westminster</name>.</p>
<fw type="catchword" rend="text-align: right;">I</fw>
<pb n="rg7_g8c_09/rg7_g8c_09_00100v.jpg"/>
<p>I enclose for your information…</p>

What if a catchword doesn’t drop below the line?

This section is for cases where a word is repeated at the beginning of the next page, but does not drop below the line on the previous page like a normal catchword, as in the following example:

Treat and tag these just as you would a regular catchword.

How do I know where to place the <pb> tags?

Place the <pb> tags true to where they appear in the image of the despatch. If a page beginnings halfway through a paragraph, then place it accordingly. Or, if a given paragraph happens to coincide with a page’s end, then place the <pb> tag after the closed </p> tag. To do otherwise would be to subvert our goal of tagging for content as it actually appears. Chat with your Despatches colleagues when you are in doubt about where to place the tags.

How do we render page numbers between pages?

These instances are rare, and usually appear in transcriptions of newsprint clippings, as in the following example:

In the above case, you can see that the number interrupts the text, right in the middle of a paragraph. In cases like this, we still use an <fw> tag, the same one we use for catchwords. However, we change the @type attribute’s value to “pageNum” as in the following example:

<fw type="pageNum" rend="text-align:center;">7</fw>
<p>…absolute lords and proprietors of the same…</p>

How do we render letters or other marks between pages?

As with numbers, other marks between pages are also a rare case, as seen in the following example:

And, as with numbers, these marks require an <fw> tag, the same one we use for catchwords. However, we change the @type attribute’s value to “sig” as in the following example: <fw type="sig" rend="text-align:center;">C</fw>

Note that the @rend attribute contains a CSS value of “text-align:center;” in order to make the “C” appear as it does in the letter: centred relative to the paragraph. Also note that the spelling of “center” in CSS is different than in our guidelines.

How do I add <pb> tags to the minutes?

Always place the <pb> tag to the right of the <div type="minute_entry"> tag, as in this example:

<div type="minutes">
   <div type="minute_entry">
      <pb n="co_305_02/co_305_02_00166v.jpg"/>
      <ab>Put by?</ab>
   </div>
</div>

Note: the minutes can sometimes span multiple pages. In this case, add <pb> tags as you would to a despatch, that is, wherever you see a page beginning in the actual document. This one can sometimes be tricky, as the minutes can jump around from page to page, or skip pages. If you’re unsure as to how to tag something, consult your Despatches colleagues.

How do I add <pb> tags to the enclosures?

Always place the <pb> tag to the right of the <div type="enclosure_entry"> tag, as in the following example:

<div type="enclosure_list">
   <div type="enclosure_entry">
      <pb n="co_305_02/co_305_02_00038r.jpg"/>
      <ab>Copy, <name key="blanshard">Blanshard</name> to <name key="helmcken_js">John Sebastian Helmcken</name>, <date when="1850-06-22">22 June 1850</date>, appointing…</ab>
   </div>
</div>

Note: we rarely have transcriptions of the enclosures. Mostly, you use these tags to indicate the start page of a given enclosure. If we do have a transcribed enclosure, then you add <pb> tags as you would to a despatch, that is, wherever you see a page beginning in the actual document.

How do I add <pb> tags to the other files?

Always place the <pb> tag to the right of the <div type="other_entry"> tag, as in the following example:

<div type="other_files">
   <div type="other_entry">
      <pb n="co_305_02/co_305_02_00055r.jpg"/>
      <ab>Draft reply, <name key="grey_hg">Grey</name> to <name key="blanshard">Blanshard</name>, No. 7, <date when="1851-04-03">3 April 1851</date>.</ab>
   </div>
</div>

Note: we rarely have transcriptions of the “other files.” As with the enclosures, these tags indicate the start page of a given “other file.” If an “other file” is transcribed, then you add <pb> tags as you would to a despatch, that is, wherever you see a page beginning in the actual document.

What if the pages are out of order?

We handle this one on a case-by-case basis. But, as a general rule, we order everything as it appears in the image collection. To do otherwise—that is, impose an arbitrary order—introduces the risk of human error. Also, if we do need to order things differently in the future, it will be easier to do so starting from a consistent base order.

The archival images are far from from perfect. Occasionally, for example, minutes are cut off, or could appear several pages later, after an entirely new letter, or even as a set of enclosures. Enclosures could also appear before or behind the despatch to which they are associated. Web-based documents, like our Despatches site, are vital to stitching these different threads together.

So, a bend to the general rule is required in cases where documents have migrated out of order. For example, if a given letter's minutes are half-way through then jump ahead ten pages, so be it. You will, on the website, see this discrepancy reflected in your <pb> tags. Each case of disorder is unique and requires attention to detail. If you find documents out of order, or are confused as to how to proceed, discuss each case with your Despatches colleagues.

What if there are miscellaneous documents toward the end of the reel?

From time to time, a given collection of images will have miscellaneous files added toward the end, just before the “index” page but after all the despatches.

Jim and his team indexed these “random” files as “other files,” and placed a list of them at the end of the final file in a given collection. To indicate that this was done, you will usually find an editorial note, such as the following example from file B63078.scx: [The following is a collection of miscellaneous document inserted at the conclusion of the despatches for 1863:]

If you do not find a note as above, then please add one! See the example below for what this would look like in XML form.

As to what to do, just add your <pb> tags as you would for any other file. Ensure that the order of the list of “other entries” reflects the order of the images, as in the following example:

<div type="other_files">
   <ab>
      <lb/>
      <lb/> [The following is a collection of miscellaneous documents inserted at the conclusion of the despatches for <date when="1863">1863</date>:] <lb/>
      <lb/>
   </ab>
   <div type="other_entry">
      <pb n="co_60_16/co_60_16_00370.jpg"/>
      <ab>John Lindley to Newcastle, <date when="1863-03-18">18 March 1863</date>, forwarding a copy of a letter concerning British Columbia. [Taken in entirety in correspondence.]</ab>
   </div>
   <div type="other_entry">
      <pb n="co_60_16/co_60_16_00371.jpg"/>
      <ab>Extract enclosed with Lindley letter above, no salutation or signature, <date when="1863-01-11">11 January 1863</date>, supporting the existing government in British Columbia as just and effective and discussing at length various aspects of the colonial situation. [Taken in entirety in correspondence.]</ab>
   </div>
</div>

Asterisks, daggers, and more!

This section covers marks intended to link bits of text. These can take a surprising diversity of forms!

Asterisks

These come in all kinds of shapes and sizes. A basic asterisk (*) can be added to your XML document with the keyboard [shift + 8]. We use the basic asterisk to indicate all asterisks in the despatches.

Daggers

Daggers function, essentially, as asterisks do: to indicate a footnote. Daggers point to a second footnote, when an asterisk is already used.

Here’s an image of a dagger, from the collection. The dagger rests above the “3”:

Here’s an image of the footnote to which the dagger refers:

If you need to represent the dagger in your XML document, then copy/paste the following symbol as needed: †

Dotted cross

Here's a rare one, usually used to indicate the continuance of text across a page fold:

If you need to represent the dotted cross in your XML document, then copy/paste the following as needed: ⁜

CSS in Your XML document

Thanks to Martin, we now use CSS to define layout elements within the despatches—this applies to such things as centring text, italics, tables, and the like. CSS allows for far greater freedom and fine-tuning.

CSS: general application

We place CSS elements inside style tags, as in the following example: <fw type="pageNum" rend="text-align:center;">2</fw>

Things are set up in such a way that, via the XSLT transformation, rend tags containing CSS will be displayed appropriately on the HTML pages, i.e., the Despatches website.

CSS: block quotations

See the Blockquotes section for CMOS’s rules for block quotes. Arguably, our method is a bit of a cheat in that we should be handling blockquotes with a blockquote tag. However, the CSS approach gives us more flexibility. The following style looks good, so we’ll stick with it for now. Also, please note that we place the blockquote text within a <p> tag.

<p>
   <hi style="padding-left:20px; display:block;">blockquote text will appear here</hi>
</p>

CSS: bold text

<hi style="font-weight: bold;">bold text will appear here</hi>

CSS: centre text

<hi style="text-align:center;">1301 N. America</hi>

Note that within the tag the american spelling for “center” is used.

CSS: italic text

<hi style="font-style: italic;">intended italic content here</hi>

CSS: list

The template below can be used for regular or numbered lists within the body text of the Despatches XML document.

<list type="ordered" style="list-style-type: none;">
   <item n="1">item here</item>
   <item n="2">item here</item>
   <item n="3">item here</item>
</list>

CSS: multiple rules in one tag (a rulesheet)

Perhaps you wish to, as in the example above, centre your text, but also affect other changes, such as italics. As in the example below, add the desired elements, separated by semicolons: <fw type="pageNum" rend="text-align:center; font-style:italic;">2</fw>

CSS: superscript

<hi style="vertical-align: super; font-size: 80%;">superscript text</hi>

CSS: superscript_underscore

<hi style="text-decoration: underline; vertical-align: super; font-size: 80%;">superscript underscore text</hi>

CSS: underline

<hi style="text-decoration: underline;">underlined text</hi>

Date tags

When you find a date within a document, first check where it occurs in the code. If it occurs within an <idno> tag, do not tag it! An instance of a date could include the year, month, and day (5 March 1847), the year and the month (April 1859), or just the year (1862).

A tagged date must contain at least a year, or the schema will list it as an error. If you find a day or month without a year, you must use your research skills to deduce the year, or ask a Despatches colleague for help.

The whole date may include a phrase such as the “16th of September, in 1862;” however, the whole date does not include noun phrases such as “The Preemption Amendment Act 1861.”

Generally, dates will appear formatted as “5 March 1847,” “9th November last,” or “19/4/62.” When tagged, the format of the date within the code always remains the same: year-month-day. When writing bios, please always use the format “5 March 1847,” note that “th” is not used after the “5.” Here are some examples: <date when="1847-03-05">5 March 1847</date> <date when="1846-11-09">9<hi style="vertical-align: super; font-size: 80%;">th</hi> November last</date> <date when="1862-04-19">19/4/62</date>

Finally, if you make a mistake in your date attribute value, the stuff between the quotes, the schema will mark it as an error. For example, if you enter <date when="1862-06-31">1862-06-31</date>, a validation error will result because June does not have 31 days, at least in this universe.

Examples of confusing date tags, and how we deal with them

<date when="1861-06-02">2<hi style="vertical-align: super; font-size: 80%;">nd</hi> June last</date>

<date when="1861-10-15">15th</date> and <date when="1861-10-21">21st of October last</date>

the <date when="1859-03-10">tenth Instant</date>

the <date when="1859-02-15">15<hi style="vertical-align: super; font-size: 80%;">th</hi>
                       </date>

As a general rule, we tag words only specifically associated with a given date. For example, this means that we usually do not tag the “the” in “the 15th Ultimo.” We base this on the TEI’s following example: Given on the <date when="1977-06-12">Twelfth Day</date>

However, we may need to tag the “the” in some rare cases for the sake of clarity. Consult your Despatches colleagues as needed.

@cert or certainty attribute

We use this attribute rarely. In simple terms, use this attribute in a date when you are not certain of its accuracy. The @cert attribute allows for for values: “high,” “low,” “medium,” and “unknown.”

Dates that lack a year or a month often pose a challenge, and can sometimes remain uncertain. Consult with your Despatches colleagues. Only after these measures should you add a @cert attribute.

Here’s an example of one in use: <date when="1863-01-26" cert="high">26 Jany</date>

Ranges, with @from and @to

Date ranges commonly turn up within the despatches: they use a modified <date> tag. Instead of @when, they use @from and @to. When tagging a date range, select the whole date range phrase, as in the following example: Should … your drafts on the amount which will be voted by Parliament for the service of the Colony for the year <date from="1862" to="1863">1862-63</date>.

Non-consecutive ranges

Some ranges will have an “and” between dates, as in “the 9th and 16th of July.” We treat these as two separate dates and use the @when attribute, as in the following example: <date when="1862-07-09">9th</date> and <date when="1862-07-16">16th of July</date>.

Ultimo [month before] and instant [present month]

Ultimo and instant are Latin terms. Often, you will find them in their abbreviated forms, such as “Ult.” and “Inst.”

Ultimo refers to the month before, and instant refers to the present month. These ones can be tricky to tag at times. When in doubt, consult your Despatches comrades. Here’s a couple of examples from the files:

Since we had last the pleasure of addressing you on the <date when="1846-08-11">11<hi style="vertical-align: super; font-size: 80%;">th</hi> Ult<hi style="vertical-align: super; font-size: 80%;">o</hi>
                       </date> this Settlement

In reply to your letter of the <date when="1849-09-22">22<hi style="vertical-align: super; font-size: 80%;">d</hi> Instant</date>;

Note that the words Instant and Ultimo are included inside the date tags. This is because they refer to the month, and it would be redundant to have the month outside the date tag. (Example: October 3, 1850 Ultimo = redundant.)

NOTE: If there’s a period after an abbreviated Inst. or Ult., that period is included inside the date tags. The only exception to this rule is if the period also indicates the end of the sentence.

Examples: <date when="1859-04-25">25<hi style="vertical-align: super; font-size: 80%;">th</hi> Ult.</date>, enclosing copies… <date when="1858-01-06">6<hi style="vertical-align: super; font-size: 80%;">th</hi> Inst</date>. Your statement that…

@notBefore and @notAfter tags

You can use these attributes in cases where the information present is too sparse to make even a vague conclusion about a given date. For example, an author may write that an event in question occurred in sometime in “either 1853 or 1854,” in this case, you could add the following attributes: either <date notBefore="1853" notAfter="1854">1853 or 1854</date>

The above example is one among many variations. Consult with your Despatches colleagues if you are unsure as to how to handle a given date.

Dates in the minutes and sad little numbers all alone

Minutes occur at the end of the primary correspondence and are often added by other authors. Minutes present a challenge to tagging dates because they are easily missed.

Authors sometimes used a non-standard abbreviation or just a single number. For example, “26 Jany” or “27” refer to the 26th and 27th of January. To establish the year, you must deduce it from the chronological sequence started at the opening of the letter. Always look at the end of the document for minutes. Dates often hide in the minutes and are extremely hard to find once missed.

Here’s an example from an actual letter, which illustrates that lonely numbers at the ends of minutes are actually dates:

<closer>
   <signed>
      <name key="blackwood_aj"> AB<hi style="vertical-align: super; font-size: 80%;">d</hi>
      </name>
      <date when="1853-08-26"> 26 August </date>
   </signed>
   <signed>
      <name key="elliot_tf"> TFE </name>
      <date when="1853-08-26"> 26/8 </date>
   </signed>
   <signed>
      <name key="peel_f"> FP </name>
      <date when="1853-08-26"> 26 </date>
   </signed>
   <signed>
      <name key="newcastle"> N </name>
      <date when="1853-08-27"> 27 </date>
   </signed>
</closer>

Dates in the general sense: no fixed date

For example, the author might write that a thing is to be done “on the 15th day of every February.” So, we do not have a specific year! In this case, we use a hyphen to indicate the missing date information, as in the following example: …and are recommmenced about <date from="--02-15" to="--02-28">the middle or end of February…</date>

In the above case, the date happens to need @from and @to. Here’s a short list of examples from the TEI guidelines on the subject: <date when="--09-11">9/11</date> <date when="--09">September</date> <date when="---11">Eleventh of the month</date>

Separating dates from signatures in a <closer> tag

This section assumes that you are familiar with how to tag dates and people. Often, despatch authors sign/initial and date on separate lines. In cases where they do not, we display them online as if they had for the sake of readability and consistency. For example, in the following image, Blackwood has initialed and dated on the same line:

On the website, it should look like this:

AB d

7/2/48.

Please note that when a <date> tag appears outside a <closer> tag, say inside a <p> tag, the <date> tag will not force a carriage return.

Dates inside <ref type=”co_ref”> tags: DO NOT TAG!

It’s redundant to tag dates within the <ref type="co_ref"> tags. Do not tag these dates. This tag generally appears after the open <opener> tag, as in the following example:

<opener>
   <ref type="co_ref">9801, CO 60/11, p. 18; received 2 November</ref>
</opener>

So, in the above example, you would ignore “2 November.”

Task checklist for XML transcription

This list can and should be used as a task checklist for each XML transcription. Hopefully, by working through this list, you will have completed all that is required to markup and edit a given correspondence. The list will grow and change as needed.

- Insert your three initials and a date [yyyy-mm-dd] within a comment, and place the comment just before the <teiHeader> tag, as in the following example:
- Add abstract placeholder after the closed </publicationStmt> tag:

<notesStmt>
   <note>Content not yet available.</note>
</notesStmt>

- Delete the superfluous head tag and contents that appear between the <div type> and <opener> tags, as in the following example, in which everything in the <head> tag should be deleted (including the tag):

<div type="public_offices">
   <head>Ward to Hawes (Parliamentary Under-Secretary)</head>
</div>

Note: we remove this tag and its contents as the information in question appears already in the teiHeader.
- Add some format the document to (1) demarcate content sections, and (2) make it easier to read long, complex files. You can add the following comments where required; you would be surprised at what a difference this makes:
- Add a couple of carriage returns between the sections you added (see #4, above), and add a carriage return between paragraphs if this makes things easier to read. As long as space out paragraphs and other sections to make the XML as readable as possible.
- Remove double space bar spaces between sentences, using find/replace.
- Compare your xml file's transcription to the scan of the original letter; make the required changes.

Indigenous Peoples <ip> tags

Mentions of Indigenous Peoples range in the despatches from pointed and detailed to vague and confusing. Starting in 1852, we’ve begun to tag all mentions of Indigenous Peoples with the following tag: <name type="ip"/>

as in the following example: <name type="ip" subtype="group">Newitty Indians</name>

In the way that we have created biography and placename entries, we hope to one day provide a rich database for Indigenous Peoples, by tagging all instances of Indigenous Peoples’ presence in a similar manner.

Adding Context: Often, Colonial Officials were very vague when referencing the activities of First Nations groups. For example, they will simply say “Indians” or “the Northern Tribes.” If this is the case please add some context within the <name> tag. For example: <name type="ip" subtype="group">Indians will freely give information to trading vessels</name>

and NOT <name type="ip">Indians</name>

We make use of @subtype to differentiate between an Indigenous individual and an Indigenous group.

Individual:

<name type="ip" subtype="individual" key="how_a_matcha">How-a-Matcha</name>

Group:

<name type="ip" subtype="group">Cowegin Tribe</name>

Insert space

If you need a set space in a line, like so. You need to insert the following XML code (without spaces): & # 1 6 0 ;

Use it as many time is a row as you need.

Line break hyphens, and the like

This section discusses how to handle words that are broken, with a hyphen or similar punctuation, where the remainder of the broken word carries on to the line below, or to the next page. As in the following example:

As you can see, the word in question is “proposal.” We want to markup the hyphen and the line break, but not render it online, in other words, we will “regularize” it in the online version.

To do this we need to use a <choice> tag so that if we choose to later, we can display the original, or the content in the <orig> tag. For now, though, our “choice” is to show the regularized version, or, the content in the <reg> tag. Please refer to the following example, taken from the image above:

On Her Majesty's behalf, to my <choice>
                          <orig>propo-<lb/>sal</orig>
                          <reg>proposal</reg>
                       </choice> that certain lands in Vancouver's…

When we choose to display the above online in the regularized format, it will look like this:

On Her Majesty's behalf, to my proposal that certain lands in Vancouver's…

But, if we choose to show the original format, it will look like this:

On Her Majesty's behalf, to my propo-

sal that certain lands in Vancouver's…

One of the beauties about the orig/reg display option is that we can configure things so that the reader can toggle between each view.

Note that there’s no content between in the <reg> tags. This is not necessarily going to be the case in every instance. If you are unsure as to how to handle a tricky line break word, space, hyphen, or similar symbol, notify your colleagues.

Links: external (to pages outside the Despatches site)

This format is used to link to a webpage that is outside of the Despatches website, such as a bibliographic entry. <ref type="external" target="http://en.wikipedia.org/">linked content</ref>

Links: internal (to other Despatches documents)

This format is used to link to another despatch, or page on the Despatches website. <ref target="cdc:V465HB03">linked content</ref>

NOTE: When you add internal links with the text of "this despatch"—as in According to <ref target="cdc:V465HB03">this despatch</ref> —make sure that the correspondence in question is, in fact, a despatch, and not another type of correspondence. When in doubt, view the letter in question on the website, which shows you the type of correspondence it is, as in the following example:

Marginalia

Marginalia appears in many of the letters. It is as diverse in location as it is in content. As far as coding it goes, in simple terms, we organize all the marginalia in one place (the end of the XML file), then we place a unique link (a <ref> tag) in the code to reflect where it would show up in the actual letter, or as close as we can get.

In the XML document, all the marginalia content should appear collected together after all the other sections of content, but before the closing <body> tag (at the end).

Here’s an example of a complete marginalia entry:

<div type="marginalia">
   <div type="marginalis" xml:id="marg1">
      <ab>Note to Sir John Pelly 21 Septr</ab>
   </div>
</div>

Once you’ve entered the marginalia as above, you need to indicate its placement within the body of text. To do this, place the following code as close as possible to where the marginalia occurs in the letter: <ref target="#marg1"/>

NOTE: You can add as many marginal notes (“marginalis”) as you like by adding the same number to both the marginalia entry and the “#marg” referent. For example, “marg2” in the marginalia entry appears where “#marg2” is placed the body text, “marg3” appears where “#marg3” is placed, and so on.

Here’s an example of what this looks like:

<div type="marginalia">
   <div type="marginalis" xml:id="marg1">
      <ab>Note to Sir John Pelly 21 Septr</ab>
   </div>
   <div type="marginalis" xml:id="marg2">
      <ab>I thought he wanted elf-shaped cookies for lunch?</ab>
   </div>
   <div type="marginalis" xml:id="marg3">
      <ab>He said that he would darn my socks. So far, I still have holes.</ab>
   </div>
</div>

So, this means that somewhere in the body of the letter we should find these three tags:

<ref target="#marg1"/>
<ref target="#marg2"/>
<ref target="#marg3"/>

FYI only: Here’s an example of a rather complex chunk of marginalia, in which a <note> tag has been added within the <marginalis> tag:

<div type="marginalia">
   <div type="marginalis" xml:id="marg1">
      <ab>
         <note xml:id="V52101_1">This text is located in the left margin and runs perpendicular to the main body text. See image scan.</note> Copy <unclear>to […]/[…]</unclear>
         <lb/>
         <unclear>[…]</unclear> with <name key="pelly">Pelly</name>
         <hi style="text-decoration: underline;">3779</hi>
         <lb/> Copy to Foreign Office<lb/> —<unclear>w<hi style="verticla-align: super; font-size: 80%; text-decoration: underline;">th</hi>[…]</unclear> Hudsons Bay Compy } 18 May / 52<lb/> Ansd 27 Sept / 52 — 5.<lb/>
         <unclear>[…]</unclear> with <unclear>[…]</unclear>
         <hi style="text-decoration: underline;">3778</hi>
      </ab>
   </div>
</div>

Misplaced addressee information

From time to time, the author of a given despatch places the addressee information at the bottom of the first page of the despatch. In these cases, we place it at the end of the digital despatch, but make a note (at the end of the addressee paragraph) as to where it appears in the original despatch.

Example as follows:

<closer>
   <name type="addressee">To the Right Hon<hi style="superscript">le</hi>
      <lb/> The <name key="grey_hg">Earl Grey</name>
      <lb/> &amp;c &amp;c &amp;c.</name>
   <note>This addressee information appears at the foot of the first page of the despatch.</note>
</closer>

Missing documents

From time to time, despatches go missing, or are placed elsewhere in the colonial volumes. Most cases of absent files require a unique approach. The following represents the quirks we have encountered thus far, and how we handled them.

Missing despatch

“Missing despatch” refers to instances where it’s clear, either from Jim's notes (which is often the case) or from the content, that a despatch is intended or supposed to be present as part of the collection.

- If the despatch is missing we still need to place an opening page image in the header (in the <biblScope type="startPageImage"> tag). Please default to the first transcribed page. For example, if the despatch is gone, but the transcription begins with the minutes, then place the first page of the minutes in the <biblScope type="startPageImage"> tag.
- Notation is required in order to tell the online reader that the despatch is missing. We indicate this in two ways.

- Indicate in [square brackets] the item thought missing from the volume, and be sure to wrap your statement in a <supplied> tag, as in the example below.
- Provide notation to indicate to the reader that the document is missing, again, as in the example below.

<supplied reason="missing">[Despatch from Blanshard to Grey.]<note xml:id="V49000A_1">This document is missing from the Colonial Office volume.</note>
</supplied>

FYI: For full examples see the following XML files: V49000A & V485HB07.

No despatch (enclosures only)

“No despatch” refers to instances where it’s clear that no letter or correspondence is associated with a given set of documents. For example, at the end of some of the volumes there might be a collection bundled together under a heading, such as “Parliamentary Papers,” or “Treasury,” and so on. Usually, we treat these bundles as we would enclosures, and, more often than not, Jim of his team have provided a descriptive paragraph for each.

- In cases where we have only enclosures, we still need to place an opening page image in the header (in the <biblScope type="startPageImage"> tag). Please default to the first page in the enclosures.

- Notation is required in order to tell the online reader that only enclosures appear in this file. We do so by providing notation to indicate to the reader that only enclosures are present, as in the example below:

[This file contains only enclosures, which appear in a collection entitled “Parliamentary Papers.” They are presented here in the order in which they appear in the Colonial volume.]

FYI: For full examples see the following XML file: V495PA04.

Missing image scan

This section refers to instances where you have a transcription, but can’t find an associated image scan with which to proof it. Possibly, Jim and his team had transcribed it from elsewhere. Or, as is likely the case, we haven’t received or uploaded the images associated with the file in question. This is usually due to the images for a given year appearing in an alternative collection, such as the National Archives Canada (NAC).

In these cases you are advised to take the following approach:

- Clean up the XML as best you can.
- Markup, as usual, the place, people, and vessel names, where present.
- Write the abstract, but leave the following comment after the opening <noteStmt> tag: “The following despatch has not yet been vetted against its corresponding image scan, which was not available at the time of this writing, [yyyy-mm-dd].”

Here’s a (shortened) example from the collection:

<notesStmt>
   <note>
      <name key="grey_hg">Grey</name> writes <name key="blanshard">Blanshard</name> to […].</note>
</notesStmt>

Multiple page image collections for one XML file

This section presumes that you have a firm knowledge of all things <biblScope> and <pb> as this situation is a little tricky. In cases where we have an image of a letterbook copy and an original copy of a given correspondence, we privilege the original, and comment out the letterbook-related tagging (see example below).

Please note that, typically, the letterbook versions of the correspondence appear in the 398/1 and 410/1 collections, at least as of this writing. This potentially complicated process is best illustrated by way of example, in which all text is black except the markup for the original documents’ metadata and content appears in blue, the markup for the letterbooks’ metadata and content appears in red, and the green to indicate new comment for document revisions:

As you can see, we comment out the former tags, rather than delete them. This allows us to awaken them in some fashion, should we choose to in the future. We place the old image referent in parentheses, however, to indicate to readers that a given file is based on an alternative image collection, as in the following example taken from above:

NAC, RG7, G8C/6, p. 156 (CO 398/1, p. 87)

Ask a team member to supply you with a copy of the “Double-image Gumbo” the text file which is an assortment of useful text that can be dragged into the XML document during this process. You’ll need to change the data from despatch to despatch accordingly. For example, changing “<idno type="page">??? </idno>” to “<idno type="page">156</idno> .”

If there aren’t any source images for the original documents, make a comment that explains that we only have the letterbook copy and proceed with <pb> tags as you would normally. Or, conversely, if we only have original images and no letterbook, do the opposite (but in this case we likely don’t have a transcribed XML which means we need to create one and that’s an entirely different story… this doesn’t happen often, thankfully).

Add formerly missed enclosures to an XML file

This section addresses the problem of what to do when you find an enclosure, or “other file,” that Jim’s team failed to add to the XML file. We put this section here as, most of the time, you will find missed files when you replace a letterbook transcription with an original (described in the section above).

Jim and his team likely missed a given enclosure because they were working from letterbook copies (the “CO 398” file family in our image collection).

Here’s the steps, with an example to follow:

- <Add a div type="other_files"> </div> tag. IMPORTANT: place this tag before the closed </body> tag, otherwise your content will appear outside the “body” of the text, which is bad.
- Within the <div type="other_files"> </div> tag, add a <div type="other_entry"> </div> tag.
- Add your <pb> tag to the right of the open <div type="other_entry"> tag. See example screenshot below.
- Within the <div type="other_entry"> </div> tag, add an <ab> </ab> tag. This tag will contain your content. Think of it as analogous to a <p> tag.
- Read through the letter as you will have to summarize its contents!
- Final step? Imitate the format and phrasing in the following example:

<ab>
   <name key="elliot_tf">Elliot</name> to <name key="hamilton_ga">Hamilton</name>, <date when="1863-03-04">4 March 1863</date>, forwarding copy of the despatch and recommending payment of the bill.</ab>

Here’s an example from the letters:

<div type="other_files">
   <div type="other_entry">
      <pb n="co_60_15/co_60-15-00024r.jpg"/>
      <ab>
         <name key="elliot_tf">Elliot</name> to <name key="hamilton_ga">G.A. Hamilton</name>, <date when="1863-03-04">4 March 1863</date>, Treasury, forwarding copy of the despatch and recommending payment of the bill. </ab>
   </div>
</div>

Duplicate content in separate XML files (originals versus letterbook copies)

This section addresses the relatively rare cases in which we have two XML files that contain the same content, with one being the original and one a letterbook copy. Here's what we do in such cases:

- Keep both files
- Note in the abstract of each that the other file exists
- In the abstract note, provide a link to each file, respectively

In general terms, we could delete the letterbook copy, and may decide to do this eventually. For now, though, it makes sense to keep both files, as it’s reasonably quick to add notes to the abstracts of each file. As of this writing, 1859 is the only year that contains both original and letterbook versions as separate files.

Example files: B597063 and V597063.

Note that we use specific wording when referring to original or letterbook copies.

Letterbook copy's abstract-wording example: This document is a letterbook copy of B597063

Original copy's abstract-wording example: See V597063 for a letterbook copy of this document.

Notes

This section assumes that you are familiar with notes, and how to add them to your XML content.

In order for notes to be displayed properly on the website, the XML needs to be coded with an “xml:id,” as in the following example: <note xml:id="V465HB01_1">note content here</note>

For the “xml:id” value, please use the despatch that you’re currently working with, an underscore, then a unique number, as shown in the above example.

What to tag, or not, in notes

First, some background. On the Despatches website, notes appears as a pop-up over the area that corresponds to the note button.

In addition, the notes in the pop-ups appear, as “footnotes,” at the bottom of the page.

- Names
- Places
- Vessels
- Dates

Do not tag the following:

- Anything that is already part of a link (any content within a <ref> tag of any kind), as in the following example: In the example above, note that “Douglas” has been incorrectly tagged (it appears with a dashed underline) in what is already a link (the green text). So, if you were to click on “Douglas”—the link within the link—things break and get screwy, as the site is not setup to handle links within links. In the XML code the incorrect code looks like this: <ref target="cdc:B58001#B00101">12719, CO 60/1, <name key="douglas_j">Douglas</name> to Lytton</ref>.
- Bibliographic information within <note> tags. For example, this citation appears within a <note> tag in the B58008.scx file: <title level="m">The Statutes of the United Kingdom of Great Britain and Ireland. 14 & 15 Victoria</title>. 1851 (London: Her Majesty's Printers, 1851). Notice that “Victoria” and “London” do not have tags, as they’re part of the reference, not the content of the despatch.

Okina: the Hawaiʻian character

Not quite an apostrophe, not quite a left-facing single quote, the ʻokina serves as a glottal-stop indicator in Hawaiʻian. The Unicode character is U+02BB and the HTML Entity (decimal) is as follows:

ʻ

For more see this link.

Quotation marks: superfluous occurrences

This section refers to an instance in which the author quotes someone else with quotation marks, and it’s clear as to where the quote begins and ends, however, the author has added an open quote on each quoted line. Here’s a good example as it would appear in the despatch actual:

Now I understand Mr Stephen to be of opinion that to give the Company "a "new interest & title in Land in these "regions would be said to be an attempt "to prolong beyond 1859" (when the present…

We’ll hide the superfluous quotes for the sake of readability, and to reduce confusion, but we’ll tag them in such a way that we can display them should we wish to, as follows:

Now I understand <name key="stephen_j">M<hi style="superscript_underscore">r</hi> Stephen</name> to be of opinion that to give the Company "a <choice>
                          <orig>"</orig>
                          <reg/>
                       </choice>new interest &amp; title in Land in these <choice>
                          <orig>"</orig>
                          <reg/>
                       </choice>regions would be said to be an attempt <choice>
                          <orig>"</orig>
                          <reg/>
                       </choice>to prolong beyond 1859" (when the present…

Note: Regular quotations will still use <q> and <soCalled> tags.

Sex attribute

This attribute is a way in which we handle whether or not a given person is male, female, or gender neutral. We use these tags so that researchers can obtain data on all of the women, men, or people who are gender neutral. For now, this attribute has been applied to women only, and in the biography files. Here’s an example from the 1860 biographies file:

<person xml:id="holroyd" sex="2">
   <persName>
      <surname>Holroyd</surname>
   </persName>

   <note>
      <p>Content not yet available.</p>
   </note>

</person>

For sex values we use The International Organization for Standardization (ISO) ISO/IEC 5218.

The four codes specified in ISO/IEC 5218 are:

- 0 = not known
- 1 = male
- 2 = female
- 9 = not applicable

NOTE: The numeric value of “2” for women means that they’re worth twice as much as a man.

Scribal filler

We need a way to handle the more bizarre and arcane textual marks produced by the various cursive eccentricities of the despatch authors. One in particular gave us recent trouble (see image below):

Rather than download and install a whole new TEI module, we used a wave dash, with an accompanying note, as seen in the following example: <note xml:id="v465HB02_2">This is a scribal filler, likely used to denote the continuation of a given paragraph. This representation is approximate; see corresponding image scan for the original mark.</note>

Here’s a wave dash that you can copy: 〜

Horizontal line extension

This one is used generally at the end of sentences. It seems to serve, in the despatches at least, the purpose of a period and a dash simultaneously, as in this example:

Add this HTML entity to your XML document as needed: ⎯

Please note that some browsers display this as an underscore ( _. )

To [sic] or not to [sic]

It may be appropriate, in some cases, to use [sic] to indicate what you see as a clear error in meaning or word choice. Always run your [sic] moves past your colleagues for approval and discussion. We also need to indicate the correction in order to give the reader the choice. As it stands, we follow the TEI Guidelines on such cases, which states the following:

It’s also possible, using the <choice> and <corr> elements, to provide a corrected reading:

I don't know, Juan. It's so far in the past now — how <choice>
                          <sic>we can</sic>
                          <corr>can we</corr>
                       </choice> prove or disprove anyone's theories?

It’s also possible to indicate the level of confidence one has in a given editorial change. We may want to consider the following as an option:

An <choice>
                          <corr cert="high">Autumn</corr>
                          <sic>Antony</sic>
                       </choice> it was, That grew the more by reaping

Further reading on apparent errors can be found here.

When a correction is made using these tags, indicate your responsibility for it using your initials:

This is <choice>
                          <sic>probly</sic>
                          <corr resp="mdh">probably</corr>
                       </choice> wrong.

Normal TEI practice would use a hash (#) before the resp attribute and point it at a full person reference in the header of the file, but for the moment we'll keep in simple and just use initials. At some point, we'll probably start building a list of bios for the people involved with the project, and we can easily transform hashless initials into hash pointers then (when there's something to link to).

It may be appropriate, in some cases, to use [sic] to indicate what you see as a clear error in meaning or word choice. Always run your [sic] moves past your colleagues for approval and discussion. We also need to indicate the correction in order to give the reader the choice. As it stands, we follow the TEI Guidelines on such cases, which states the following:

It’s also possible, using the <choice> and <corr> elements, to provide a corrected reading:

I don't know, Juan. It's so far in the past now — how <choice>
                          <sic>we can</sic>
                          <corr>can we</corr>
                       </choice> prove or disprove anyone's theories?

It’s also possible to indicate the level of confidence one has in a given editorial change. We may want to consider the following as an option:

An <choice>
                          <corr cert="high">Autumn</corr>
                          <sic>Antony</sic>
                       </choice> it was, That grew the more by reaping

Further reading on apparent errors can be found here.

When a correction is made using these tags, indicate your responsibility for it using your initials:

This is <choice>
                          <sic>probly</sic>
                          <corr resp="mdh">probably</corr>
                       </choice> wrong.

Normal TEI practice would use a hash# before the resp attribute and point it at a full person reference in the header of the file, but for the moment we'll keep in simple and just use initials. At some point, we'll probably start building a list of bios for the people involved with the project, and we can easily transform hashless initials into hash pointers then (when there's something to link to).

Strange strings, funny tags, and other legacy issues

This section is for examples of strange tags and the like, which occurred when we transformed the old digital collection from Waterloo script to XML. In simple terms, think of these instances as ghosts in the code. We handle them on a case-by-case basis. Please add to this list as you encounter new quirks. <note xml:id="B00501" n="B5800501"/>

Keep the tag above as is. Our <note> tags don’t look like them. These are leftovers from the notation that Jim and his team added to, mostly, the 1858 despatches. These don’t seem to break the site (the notes work online) so we’ll leave them as is for now. Last count: over 600 instances, mostly in the 1858 files. <milestone unit="section" rend=".in -10 +0"/>

Ignore <milestone> tags. We see these <milestone> tags from time to time, and in various forms. Generally, they mark instances of tables, or table-like things. Please leave them alone. We’ll use them at some point, even if it’s to replace them with proper XML tables.

Superscript and abbreviation conundrums

Often, the despatch authors abbreviate to save space and ink, and to annoy you personally.

In so doing, they can be a little ham-handed in their cursive when it comes to indicating distinctly whether they intend a superscript, an abbreviation, a superscripted period, or an underlined superscript. As a general rule, we try to represent the text as closely as possible. So here’s a list of some common confusers, and how to handle them:

(1) Text is clearly smaller and floating above the usual cursive line, usually at the end of a word: use only a superscript tag. <hi style="vertical-align: super; font-size: 80%;">content here</hi> Example: Govr

(2) Text is clearly smaller and floating above the usual cursive line, but it has a single line or dot below it: this is likely to indicate a line, or underscore, under the superscript. The author intends to make it clear to the reader the presence of a superscript, so we reproduce this as follows: <hi style="text-decoration: underline; vertical-align: super; font-size: 80%;">content here</hi> Example: Govr

(3) Similar to (2), but it’s clear that the single dot is to the right of the superscripted letter or letters, and in line, or thereabouts, with the main text: this is likely a period to indicate an abbreviation, so follow this example (note that the period is to the outside of the superscript tag): Gov<hi style="vertical-align: super; font-size: 80%;">r</hi>. Example: Govr.

(4) Similar to (3), but the period is on the same level as the superscript: place the period inside the superscript tag in order to superscript the period, as in the following example: Gov<hi style="vertical-align: super; font-size: 80%;">r.</hi> Example: Govr.

(5) Text is clearly smaller and floating above the usual cursive line, but it has two lines or dots below it, or a dot and line in an unclear order or location: use your judgment, based on the examples above.

Of course, many intentions are possible. Likely, though, two lines, dots, or marks, in any configuration are meant to indicate an underscored superscript, followed by period to indicate an abbreviation. When in doubt ask for a second opinion.

Transcribed minutes on “enclosures” and on “other files”

Note that transcribed minutes that appear on enclosures will not be within a <div type="minutes">, they will appear only as <div type="minute_entry">; we so because we want the minutes to appear online as though they’re under the “Documents enclosed with the main document (not transcribed)” divider.

- If the transcribed minutes appear on the first page, then DO NOT insert a <pb> tag.
- If the transcribed minutes occur on subsequent pages, then insert a <pb> tag that links to the page that contains the minutes; if, in these minutes, the text covers multiple pages, then insert <pb> tags at each page beginning, as you would for the despatch letters.

@type="unavailable" vs. "incomplete"

This value is added to people, place, or vessel entries that are either incomplete or unavailable. Here’s the current meaning for each:

- "unavailable" means that we’ve added no information to the entry, just its name, place name, or vessel name, respectively.
- "incomplete" means that we’ve added cursory information to a given entry, but it reads as unfinished, and therefore needs more research and content.

In the biography entries, use the following tags: <persName type="unavailable"/> <persName type="incomplete"/>

In the places entries, use the following tags: <placeName type="unavailable"/> <placeName type="incomplete"/>

In the vessel entries, note that things change slightly, and the attribute value has to be added as a “subtype” to be valid: <name type="vessel" subtype="unavailable" key="alexandra"/> <name type="vessel" subtype="incomplete" key="alexandra"/>

Unclear tag

This tag is used to handle text that’s too garbled or difficult to make out. Typically, since Jim and his crew were so good at transcribing the original text, you’ll end up using this tag infrequently. Should you need it, it’s as follows: <unclear>content here</unclear>

Wavy or squiggly lines and underlines

This situation is a little tricky and should be handled on a case-by-case basis. Here’s an example of a need for squiggly lines:

The Unicode name for squiggly lines is “wavy low line.”

Copy this symbol to your XML document as needed: ﹏

Remember that each “﹏” will only fill the width of one character space. It takes quite a few to make a line!

Colonial Despatches style guide

Abbreviations

Currently, the only abbreviation for organizations that we use is HBC (Hudson’s Bay Company). CMOS recommends that less familiar abbreviations aren’t to be used unless the word appears more than five times (see CMOS 10.3).

We use abbreviations for metric (km, m, cm) and write out imperial (mile, foot, inch). We do not, however, use an abbreviation for “street.”

CMOS recommends that periods are generally not to be used in abbreviations (see CMOS 10.4). Periods are only used in abbreviations that end in a lower case letter (vol., a.m., p.m., Mr., Ms.), except for measurements.

Here are some examples:

- a 29 m long, 303-tonne sloop
- Mr. President
- The river is 236 km long.
- 100 kmh (kilometres per hour)
- He lived on Scott Street.

Abbreviations: spaces between them

Names use spaces. From CMOS 10.12:

Initials standing for given names are followed by a period and a space. A period is normally used even if the middle initial does not stand for a name (as in Harry S. Truman).

- Roger W. Shugg
- P. D. James
- M. F. K. Fisher

If an entire name is abbreviated, spaces and periods are usually omitted.

- FDR (Franklin Delano Roosevelt)
- MJ (Michael Jordan)

but

- H.D. (pen name for Hilda Doolittle, with periods but no space between initials because it’s a special case)

Abbreviations of provinces, territories, and states

Provinces, territories, and states are spelled out in text. Abbreviations may be used in bibliographies using the two-letter postal abbreviations (see CMOS 10.28).

In running text, spell out “British Columbia” as a noun; reserve “BC” for the adjective form only (see CMOS 10.32). We don’t place periods around “BC” either (see CMOS 10.4).

Ellipses

From the CMOS 13.50: Ellipses defined: “An ellipsis is a series of three dots used to signal the omission of a word, phrase, line, paragraph, or more from a quoted passage.” Most often, we use ellipses to indicate that we have removed a portion of text.

Use the following HTML entity (horizontal ellipsis) in your XML document: &#8230;

Or, copy/paste this example ellipsis into your XML document: …

Add ellipses with no spaces either side of the text. We treat each ellipsis as we would an em-dash, with no spaces either side of the punctuation. Our style does not follow the CMOS style, where an ellipsis is "three spaced periods" (see 13.50: Ellipses defined) with spaces either side of the ellipsis. We think it simpler to use the Unicode character &#8230;.

Ellipsis usage:

- Within a sentence: I report that the ship…has landed at the expected port.
- Before a period: It was a condition of the sale….
- Following a period in the preceding sentence: The spirit of our ship is sound…. On the other hand, the crew has become indolent.
- In brackets, we add spaces preceding and following the bracketed ellipses: The crew decided then…to make […] all the the grog vanish that night. Use bracketed ellipsis only in cases of disambiguation, that is, where the original sentence has ellipses and you have also omitted text, as in the example above.
- We use bracketed ellipsis in citations, usually to shorten long titles: Baggins, Frodo. A Discourse on Elves, Dragons, and Packing Advice for Middle Earth […]. The Shire, 2942. In this, we follow the suggestion in CMOS 14.97: Very long titles may be shortened in a bibliography or a note; indicate such omissions by the use of bracketed ellipses.". Note that the "[…]" is not in italics, as it is not part of title.
- In parentheses, we add spaces preceding and following the parenthetical ellipses: "The next day, the crew was (…) royally hungover."

More CMOS ellipsis usage:

- 13.53: Ellipses with periods: “Note that the first word after an ellipsis is capitalized if it begins a new grammatical sentence. Some types of works require that such changes to capitalization be bracketed; see 13.21. See also 13.58.”
- Instances of this should be rare, but see 13.56: Ellipses for the omission of whole or partial paragraphs, as needed.

Oxford/serial comma

Oxford, or serial, commas are used in all Despatches writing. We do so to avoid ambiguity, as CMOS 6.19 suggests.

Oxford/serial commas are used “when a conjunction joins the last two elements in a series of three or more.” The comma is placed before the conjunction. For example, “she posted pictures of her parents, the president, and the vice president.”

Punctuation inside or outside of quotation marks?

Punctuation like periods and commas go inside of quotation marks, while punctuation like question marks and exclamation marks go either inside or outside depending on the content of the quote.

See this table from CMOS, section 6.1:

Blockquotes

Chicago differs from MLA in this respect in that MLA calls for blockquotes for quotes over four lines in length. CMOS, however, advises blockquotes for a hundred words or more (at least six to eight lines of text in a typical manuscript), unless “quotations are being compared or otherwise used as entities in themselves” (see CMOS 13.10).

The latter instance is a judgment call, of course, and if you’re unsure, please consult your Despatches colleagues.

Finally, see the CSS: block quotations section for how to tag your blockquotes in XML.

Preferred spelling

Use Canadian spelling in all cases except for “despatch” (not “dispatch”). Below is a word list to help you with the correct spelling for Despatches. Please consult your Despatches colleagues if you think a word should be added to the list.

Remember, correct spelling includes correct capitalization and hyphen use. When in doubt, here’s a reliable source for Canadian spellings: The Canadian Oxford Dictionary (requires login on a computer outside of the library). Luke Mastin’s Canadian, British and American Spelling website is also a helpful tool, but make sure to double-check the preferences on the website against the COD or this list since there are a few inconsistencies.

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

A

- Aboriginal
- abridgement
- acknowledge, acknowledgement
- advertise
- adviser
- aesthetic
- aging
- airplane
- aluminum
- amid (not amidst)
- among (not amongst)
- amortize, amortization
- amphitheatre
- analogue
- analyze
- anemia, anemic
- appetizer
- arbour
- archaeology
- ardour
- armour, armoured
- artifact
- authorize
- axe

B

- balk
- bandana
- banister
- baptize
- barrelled, barrelling
- BC Genesis
- behaviour
- behoove
- belabour
- blond
- brunette
- burned (not burnt)
- by-product

C

- calibre
- cancel, cancelled, cancelling, cancellation
- candour
- capitalize, capitalization
- catalogue
- categorize, categorization
- centimetre
- centre, centred, centring
- checkered
- cheque (form of payment)
- cipher
- civilize, civilization
- clamour
- clangour
- co-author
- colonize
- colour, colouring, coloured
- commercialize
- compel, compelled, compelling
- computerize
- co-op, co-operative education
- co-opt
- counsel, counsellor (an adviser), counselling
- councillor (a member of a council)
- counter-attack
- cozy
- criticize
- crueller, cruellest
- crystalline
- crystallize
- curb
- customize

D

- defence
- demeanour
- demoralize
- dependant (noun), dependent (adjective)
- despatch
- dialled, dialling
- dialogue
- diarrhea
- digitize
- disc (recording), disk (computers)
- dishevelled
- distil
- double-check
- draft
- dreamed (not dreamt)
- duelled, duelling
- dwelled (not dwelt)

E

- e-book
- economize
- email
- empathize
- emphasize
- enamour
- encyclopedia
- endeavour
- enrol, enrolled, enrolling, enrolment
- ensure (make certain)
- enthral, enthrallment
- equalled, equalling
- ethnic

F

- familiarize
- favour, favourite, favourable
- fervour
- fibre
- filename
- finalize
- First Nation
- flavour
- flutist
- focused, focusing
- forever
- fuel, fuelled, fuelling
- fulfill, fulfilled, fulfilment, fulfilling
- funnelled, funnelling
- furor

G

- galvanize
- gauge
- generalize
- glamour
- goodbye
- grey
- gruelling

H

- harbour
- harmonize
- HBC (Hudson’s Bay Company)
- hemorrhage
- hireable
- home page
- honour, honourable, honoured, honorary
- hospitalize
- humour, humorous
- hypnotize
- hypothesize

I

- idolize
- immortalize
- imperilled, imperilling
- industrialize, industrialization
- Indigenous
- initialize, initialization
- initialled, initialling
- inquire, inquiry
- install, installment, installation, installing
- instill
- institutionalize
- insure (secure payment of)
- Internet

J

- jeweller, jewellery
- journalize
- judgment

K

- kidnapped
- kilogram
- kilometre
- kneeled (not knelt)

L

- labelled, labelling
- labour, labourer, laborious
- leaned (not leant)
- learned (not learnt)
- leaped (not leapt)
- legalize
- levelled, levelling
- libellous
- licence (noun), license (verb)
- likeable
- line break
- litre
- liquefy
- lower case
- lustre

M

- macabre
- manoeuver
- marshal
- marvel, marvelled, marvelous
- maximize
- meagre
- medallist
- memorialize
- memorize
- mesmerize
- metre
- militarize
- milimetre
- minimize
- misdemeanour
- mobilize
- modelled, modelling
- mould
- moustache
- movable

N

- nameable
- neighbour, neighbourhood
- neutralize

O

- odour, odorous
- offence, offensive
- online
- optimize
- organize, organization

P

- panelled, panelling, panellist
- parallel, paralleled, parallelling
- parlour
- peddler
- per cent
- personalize
- phony
- plow
- polarize
- practice (noun, adjective), practise (verb)
- pre-eminent
- pre-exist
- pre-war
- prioritize
- program, programmed
- propeller
- pulverize
- pummelled, pummelling
- pyjamas

Q

- queue, queueing

R

- raccoon
- rancour
- racquet (sports equipment)
- rateable
- re-educate
- re-elect
- re-enter, re-entry
- re-examine
- realize, realized, realization
- recognize
- revelled, revelling
- rigour, rigorous
- route, routing
- rumour

S

- sabre
- sanitize
- saviour
- savour, savoury
- sceptre
- scrutinize
- sensationalize
- shrivelled, shrivelling
- signal, signalled, signalling
- sizeable
- skeptical
- skilful
- smelled (not smelt)
- smoulder
- sombre
- space bar
- specialize, specialization, specialty
- spectre
- spelled (not spelt)
- spilled (not spilt)
- splendour
- spoiled (not spoilt)
- squalor
- stabilize
- standardize, standardization
- sterilize
- story (tale), storey (floor of building)
- stylized
- succour
- summarize
- symbolize
- sympathize
- synthesize

T

- terrorize
- theatre
- tonne (metric), ton (imperial)
- total, totalled, totalling
- toward
- tranquility
- tranquilize
- travel, travelled, traveller, travelling
- tremor
- tumour
- tunnelled, tunnelling

U

- unionize
- upside down (adverb, adjective), upside-down (attributive adjective)
- utilize (but you should just use “use,” see a list of things Kim Blank hates)

V

- valour, valorous
- vapour
- vice-president
- vigour, vigorous
- visualize, visualization

W

- wagon
- web page, website
- while (not whilst)
- wilful
- work team
- worshipped

X

Y

- yogurt

Z

Capitalization

Capitalization of cities, towns, forts, and political divisions

Words like empire, confederation, province, fort, and town are capitalized when they follow a proper name and are used as an accepted part of the name. When preceding the name, such terms are usually capitalized in names of countries but lower case in entities below the national level (see CMOS 8.51).

Examples (add more as they occur):

- the province of Ontario
- Massachusetts Bay Colony; the colony at Massachusetts Bay
- the Indiana Territory; the territory of Indiana
- the Northwest Territory; the Old Northwest
- New York City; the city of New York
- the British Empire; the empire

When a specific government body or organization is meant rather than the place, the government body is also capitalized—for example, he worked for the Province of Ontario (see CMOS 8.52).

Capitalization of directions

Compass points are not capitalized when they are used to explain directions such as “to the north of Vancouver” or “eastern Canada.” However, compass points are capitalized when they refer to places such as “North Vancouver” or “East Canada” (see CMOS 8.47). Further examples include the following: “he went to the West Coast for his holiday,” but “he went to British Columbia's west coast.”

Capitalization of ethnic and other national groups (Indigenous, Aboriginal, First Nations)

Ethnic and national groups are capitalized. Adjectives associated with these names are also capitalized (see CMOS 8.38 and the UVic Style Guide Section 5.2).

Capitalization of military and other titles

As for military titles, we’ve settled on CMOS's approach to this matter: “in formal academic prose, most such titles are capitalized only when used as part of a person’s name” (see CMOS 8.24).

Some pertinent examples are as follows, as taken from CMOS 8.24:

- the admiral; Chester W. Nimitz, fleet admiral; Admiral Nimitz, commander in chief of the Pacific Fleet; the captain; Captain Frances LeClaire, company commander
- the sergeant; Sergeant Carleton C. Singer; a noncommissioned officer (NCO)
- the British general; General Sir Guy Carleton, British commander in New York City; General Carleton.

As for other titles, such as nobility, CMOS states the following:

“Unlike most of the titles mentioned in the previous paragraphs, titles of nobility do not denote offices (such as that of a president or an admiral). Whether inherited or conferred, they form an integral and, with rare exceptions, permanent part of a person’s name and are therefore usually capitalized. The generic element in a title, however (duke, earl, etc.), is lowercased when used alone as a short form of the name.”

Some pertinent examples are as follows, as taken from CMOS 8.32:

- the prince; Prince Charles; the Prince of Wales
- the duke; the duchess; the Duke and Duchess of Windsor
- the marquess; the Marquess of Bath
- Lord Bath; the earl; the Earl of Shaftesbury; Lord Shaftesbury; Anthony Ashley Cooper, 7th (or seventh) Earl of Shaftesbury; previous earls of Shaftesbury.

See CMOS 8.32 for more, particularly on the differences with British usage.

Capitalization of places

Names of places, including mountains, rivers, islands, etc., are capitalized. In cases where terms like “mountain,” “ocean,” and “river” are included in the name of the place they are capitalized as well. See CMOS 8.47 to 8.58 for clarification.

Examples:

- the Pacific Station
- Bamfield Inlet
- the Gulf
- Greater Victoria
- the City of Victoria
- the metropolitan area
- the United States
- the republic
- the Union
- the river Fraser
- Fraser River
- London Bridge
- the Pyramids
- the Egyptian pyramids
- the West Wing

Capitalization of political parties

Official names of political parties and organizations are capitalized. Words like “party,” “union,” and “movement” are capitalized as well if they are included in the name of the political party or organization. See CMOS 8.66 for clarification.

Examples:

- Whigs [except when used as as adjective, as in, “he behaved whiggishly.”]
- Tories
- the Democratic Party
- democratic nations
- Loyalist(s)

Capitalization at the start of quotations

Capitalization within quoted material can be changed to suit the context (within reason). These changes can be made “silently,” that is, they don’t require square brackets to indicate that a change has been made since the meaning and word choice of the quoted material remains the same. See CMOS 13.18 and 13.7 point three for clarification.

Example: After his stint in politics, and, with his children either abroad or “leading frivolous lives,” Dunsmuir retreated to a solitary life on his estate at Hatley Park.

Sentence case for headers

The Despatches team have come to an agreement that all headlines will be in sentence case rather than title case. Sentence case in a header is indicated by the capitalization of the first word and proper nouns only, for instance you would write: “Blurb about sentence case” rather than “Blurb about Sentence Case.” So why is this the better option?

Sentence case is actually the style that is internationally used. Title case has really only been adopted in the “North American” context, so the Despatches are hopping on the bandwagon! Therefore, by using sentence case, it makes it more accessible to a wider audience to read, understand, and note what is a proper noun and what is not. While we are at it, let’s discuss more reasons why sentence case is better…

Google uses sentence case due to its superior readability, tone, functionality, and comprehension. So, as mentioned before, it will reach a broader range of people. In this view, sentence case is superior because it is the natural way we read. How crazy would it be if we were reading a book like this: “Once Upon a Time There was a Little Bird…” In this way, sentence case is a simple and organic way to read for the human mind. Simply, sentence case is: easier to write, easier to read, and easier to translate.

Last but not least, it has been stated by many people who prefer sentence case, that it has an approachable tone. What this means is that it is less bold and “in your face” as title case can be (which does have its own perks); but it creates a connection with the people reading it. One could say that in this way, sentence case creates a universality through the way that it is written.

Comma with city plus province/state

When following the name of a city, whether spelled out or abbreviated, the names of states, provinces, and territories are enclosed in commas (see CMOS 10.29). For example: Victoria, BC, is a nice city.

Periods in a list

Periods should only be used at the end of a bullet or list point if the point contains a full sentence. If the point is a phrase then a period is not used.

Hyphens

Hyphens are tricky--CMOS provides a comprehensive hyphenation table that can be used to answer most questions. Here are a few common issues of proper hyphenation:

- Canada-US border (not Canada/US border)
- 4 km wide river (not 4-km-wide river)

Newspaper titles

Omit the “the” from newspaper titles. For example, write the British Colonist not The British Colonist. See CMOS 14.193 for more.

Don’t forget to italicize newspaper titles. Be sure to wrap them in a <title> tag, as in the following example: edition of the <title level="j">British Colonist</title> gives notice Note: as stated above, “the” is left outside of the <title> tag.

Numbers: to write out or not?

Spell out numbers from zero through nine, use a numeral for 10 and above (see CMOS 9.3).

Try to avoid starting a sentence with a number. If you have to, spell out the number that starts the sentence (see CMOS 9.5).

When an abbreviation is used for a unit of measure (i.e. km, m, cm), then the quantity must always be expressed by a numeral (see CMOS 9.16).

Words versus monetary symbols and numerals

Isolated references to amounts of money are spelled out for whole numbers of one hundred or less (see CMOS 9.2 and 9.3).

Examples:

- Correct: $100,000
- Correct: Ten dollars
- Incorrect: 100,000 dollars
- Incorrect: $10

Possessives and attributives

CMOS has changed the convention of correct singular form possessives (see CMOS 7.17). For example, instead of “Douglas’ letter” it’s now “Douglas’s letter.” This rule includes nouns that end in a silent “s,” such as “Descartes’s three dreams” (see CMOS 7.18).

Note: plural possessives continue as before with an apostrophe alone. For example, “the Lincolns’ marriage.”

Roman for Latin words and abbreviations

Unlike most words in a foreign language, commonly used Latin words and abbreviations should not be italicized.

Examples: Ibid., et al., ca., passim

However, “sic” should be italicized due to its distinct use in quotations. For example, “mindful of what has been done here by we [sic] as agents of principle” (see CMOS 7.55).

Ships and other named vessels

Names of ships and vessels are capitalized and italicized. The word “ship,” or other vessel types, should not be used in cases where the abbreviations USS (United States ship) or HMS (Her or His Majesty’s ship) precede the name of the vessel. These abbreviations aren’t italicized either.

Some examples from CMOS 8.116:

- Mars global surveyor; Mars polar lander; Phoenix Mars lander; Phoenix
- the space shuttle Discovery
- the Spirit of St. Louis
- HMS Frolic; the British ship Frolic
- SS United States; the United States
- USS SC-530; the US ship SC-530

Speeds

As ever, we list speeds in metric. Here’s an example:

Knots (ship speed measurement) should be converted to “kmh” (kilometres per hour), as in 22 kmh.

XML style preferences

<soCalled> and <q> tags

<soCalled> elements are used for nicknames, scare quotes, terms in Indigenous languages, and informal event names (e.g. Pig War). <q> elements are used to replace quotation marks around quotes. <q> elements can also be nested in instances where there’s a quote within a quote.

Company and store names do not have quotation marks around them. The same rule applies for instances of Her Majesty and places (unless an informal name is used).

Here’s some examples of <q> elements: Unfortunately, the area was leased to the Hudson’s Bay Company at the time and the Colonial Office could not <q>undertake to say on which terms land shall be offered in that island</q> and declined his request. his body was found with <q>a Bag Containing Gold Dust value 69 Dollars and 50 Cents--In Silver Coin One Dollar &amp; 85 Cents and a <q>Colt Revolver</q>,</q>

Here’s some examples of <soCalled> tags used to indicate informal terms/names: However, in 1856, Walker did become president of Nicaragua and implemented an <soCalled>Americanization</soCalled> program to encourage U.S. citizens to immigrate there. The water boundary issue resulted in what is now known as the <soCalled>Pig War.</soCalled>

Here’s an example of the <soCalled> tag used for a term in an Indigenous language. Note that the tag is used around the term and its English translation: The Lummi named the area <soCalled>what-coom</soCalled>, or <soCalled>noisy, rumbling water</soCalled>, in reference to a waterfall near Bellingham Bay.

Canadian vs. American spelling in tags

Note that tags often use American spelling preferences. While we use Canadian spelling like in “centre” throughout running text, “center” needs to be used when marking up text in Oxygen.

For example: <hi style="text-align:center;">He stood in the centre of the crowd.</hi>

In-text date format

For dates within the text of our writing we break from CMOS and use MLA "humanistic" style of formatting which is integer of day, month spelled out, and integer for year.

15 June 1859

Writing tips

(For a streamlined version of this section and workflow directions specific to the Professional Communication Directed Reading program please see the Colonial Despatches Directed Reading document.)

Since there are so many authors working on the Despatches website, we want to keep the writing consistent. With this in mind, here’s a working list to consider when you begin writing:

- Know the difference between (1) direct quotation, (2) paraphrasing, and (3) summary. Honestly, if you’re shaky on any of this then you should probably not write anything until you have it dialed in.

- See this University of Toronto article on paraphrasing and summary.
- See the same source as above for an article on quotation.

- Write in present tense. That is, “Douglas writes,” not “Douglas wrote.” For more information see CMOS 5.129.
- Avoid the passive voice. If you don’t know what passive voice is, read CMOS 5.118.
- Avoid gerunds. If you don’t know what a gerund is, read CMOS 5.112.
- Over the years, UVic's Kim Blank has accrued a list of the things Kim Blank hates. Mostly, we hate the same things.
- Use last names when you refer to a person after their full name has been mentioned once already. For example, write “Douglas reports that” not “Governor Douglas” or “James Douglas” after the first instance of “Governor James Douglas.”
- For the most part, use Canadian spelling, eh. See the Preferred Spelling section for a detailed list.
- Avoid parenthetical interjections (like this), use commas, em dashes, or rework the sentence.
- Do NOT put double spaces between sentences! And don’t use double returns between paragraphs.

Chicago-style citations

Our reference system: Chicago-style endnotes

When website readers click on tagged person, place, or vessel, a pop-up note appears, in order to provide for the reader further context. These pop-up notes are well-researched mini essays of a sort, and cited as one would an academic essay. However, these pop-ups are neither truly notes nor essays exactly, so we treat them as Chicago-style “notes,” as this is the closest definition we can all agree upon.

When in doubt about anything to do with this decision, refer to your Despatches colleagues or refer to the CMOS website as needed.

Notation numbers

Each notation number should have a corresponding endnote at the end of the entry. Here is what a typical note looks like on the website (circled in red):

The notation numbers in a given entry should appear in numerical order from top to bottom. Numbers are to be placed to the right of the period, and any other punctuation, e.g. outside quotation marks. No notation number mid-sentence please. Colonial Despatches prefers all notations at the end of sentences (indicating more than one source if necessary).

XML code placeholder for a number (copy/paste): <bibl corresp="#xml:id_b_corresponding number here"><hi style="vertical-align: super; font-size: 80%;">number goes here</hi></bibl>

Example from the V60 bios: <bibl corresp="#allison_b_3"><hi style="vertical-align: super; font-size: 80%;">3</hi></bibl>

Basic endnotes

Each endnote should have a corresponding number notation in the entry. We use this system as it makes for improved readability, as opposed to, say, MLA, in which each reference requires a parenthetical citation at the end of the sentence. This latter system can look pretty cluttered in such a small chunk of text. These endnotes will have corresponding <bibl> tags that link to the note in the text by using a unique xml:id in the form shown below, with the note content inside.

XML code placeholder for an endnote (copy/paste): <bibl xml:id="xml:id here_b_number of endnote here">Citation here.</bibl>

Example from the V60 bios: <bibl xml:id="allison_b_3">3. <ref target="cdc:B60070">Douglas to Newcastle</ref>, 3 August 1860, 9346, CO 60/8, 2.</bibl>

Endnote punctuation and formatting minutia

This section is intended to show you how to punctuate and format your endnotes and bibliography entries. Here are some endnote and bibliograpy punctuation rules, in no particular order:

<title> tags with an attribute of level="a" should appear after, or outside, punctuation marks. Here is an example from a <bibl> entry for a journal:

<bibl xml:id="shifting_perspectives_b_6">6. Eve Tuck and K. Wayne Yang, <title level="a">Decolonization Is Not a Metaphor,</title>
   <title level="m">Decolonization: Indigeneity, Education &amp; Society</title> 1, no. 1 (2012): 6.</bibl>

Note that if we wrap a <ref> tag around an article title, we place the <ref> tag inside the <title> tags, but before the comma:

<bibl xml:id="shifting_perspectives_b_6">6. Eve Tuck and K. Wayne Yang, <title level="a">
      <ref type="external" target="https://jps.library.utoronto.ca/index.php/des/article/view/18630/15554">Decolonization Is Not a Metaphor</ref>,</title>
   <title level="m">Decolonization: Indigeneity, Education &amp; Society</title> 1, no. 1 (2012): 6.</bibl>

<title> tags with an attribute of level="m" should appear before, or inside, punctuation marks. This is because wrapping text in a level="m" tag renders as italics, not quotation marks, on the website. Here is an example from a <bibl> entry for a book: <bibl xml:id="indianact_b_5">5. Bob Joseph, <title level="m">21 Thing You May Not Know About the Indian Act: Helping Canadians Make Reconciliation with Indigenous Peoples a Reality</title> (Port Coquitlam: Indigenous Relations Press, 2018), 94.</bibl>

Examples of endnotes

Book and monograph example

<bibl xml:id="carrall_ww_b_8">8. Tom Snyders and Jennifer O'Rourke, <title level="m">Namely Vancouver: The Hidden History of Vancouver Place Names</title>, (Vancouver, BC: Arsenal Pulp Press, 2001), 57.</bibl>

Journal article example

<bibl xml:id="onslow_b_4">4. Barry M. Gough, <title level="a">
      <ref type="external" target="http://www.jstor.org/stable/4049600?seq=12">The British Reoccupation and Colonization of the Falkland Islands</ref>
   </title>, <title level="m">Albion: A Quarterly Journal Concerned with British Studies</title>, 22 (Summer 1990): 271-272.</bibl>

Despatch example

<bibl xml:id="pike_b_4">4. <ref target="cdc:V635AD01">Paget to Rogers (Permanent Under-Secretary)</ref>, 29 June 1863, 6392, CO 305/21, 3.</bibl>

Newspaper example

<bibl xml:id="parker_cs_b_2">2. <title level="a">
      <ref type="external" target="https://www.geni.com/people/Charles-Parker-MP/6000000026818072930">Obituary</ref>
   </title>, <title level="j">Daily Telegraph</title>, 21 June 1910, 9.</bibl>

Website source examples

Web page, with author

<bibl xml:id="africa_b_1">1. S. Swiggum, <title level="a">
      <ref type="external" target="http://www.theshipslist.com/ships/descriptions/ShipsA.html">Ship Descriptions - A</ref>, </title>
   <title level="m">The Ships List</title>.</bibl>

This is what the above example looks like on the website:

Web page, no author

<bibl xml:id="alarm_b_2">2. <title level="a">
      <ref type="external" target="http://www.pbenyon.plus.com/18-1900/A/00134.html#Expedition">Alarm</ref>, </title>
   <title level="m">Index of 19th Century Naval Vessels</title>.</bibl>

This is what the above example looks like on the website:

Web page, PDF

In the following example, we have a PDF link, that links to a PDF that has page numbers:

<bibl xml:id="bruce_b_1">1. <title level="a">
      <ref type="external" target="http://www.proni.gov.uk/introduction_hervey_bruce-2.pdf">Hervey/Bruce Papers</ref>
   </title>, <title level="m">Public Record Office of Northern Ireland</title>, 15.</bibl>

Online dictionary or biography

In the following example, we have an online dictionary or biography:

<bibl xml:id="chesson_fw_b_1">1. H.C. Swaisland, <title level="a">
      <ref type="external" target="http://www.oxforddnb.com/view/article/38853.">Chesson, Frederick William</ref>
   </title>, <title level="j">Oxford Dictionary of National Biography</title>.</bibl>

Archival sources

For archival material, we use a format based off of Chicago style. Begin with the name of the archive, followed by the title of the document, marked up with <title level="u">, then add the additional document information.

Below is an example from the Library and Archives Canada (LAC). Note that <bibl xml:id="shrapnel_h_b_1">1. LAC, <title level="u">Commissions of Henry Needham Scrope Shrapnel</title>, MG 24 F 113, Vol 3, File 1.</bibl>

Multiple citations

Note that we don’t include the pop-up content in the following example. It’s presumed that the notation numbers are added correctly.

<listBibl>
   <bibl xml:id="smith_w_b_1">1. Hubert Howe Bancroft, <title level="m">The Works of Hubert Howe Bancroft. Volume XXXII. The History of British Columbia. 1792-1887</title>, (San Francisco: The History Company, Publishers, 1887), 617.</bibl>
   <bibl xml:id="smith_w_b_2">2. Milton, William Fitzwilliam, viscount, <title level="m">A History of the San Juan Water Boundary Question, As Affecting the Division of Territory between Great Britain and the United States</title>, (London: Cassell, Petter, and Galpin, 1869), 256-257.</bibl>
   <bibl xml:id="smith_w_b_3">3. <ref target="cdc:V59031">Douglas to Lytton</ref>, 8 August 1859, 9570, CO 305/11, 29.</bibl>
</listBibl>

Multiple citations in one note

Always use one number to indicate multiple sources, but add a semicolon between the sources in the <bibl> entry, as in the following example: <bibl xml:id="anderson_d_b_4">4. S. Van Kirk, <title level="m">Women in Fur Trade Society in Western Canada, 1670-1870</title>, (Winnipeg: Watson &amp; Dwyer Pub., 1980), 220-30; F. Pannekoek, <title level="m">A Snug Little Flock: The Social Origins of the Riel Resistance, 1869-70</title>, (Winnipeg: Watson &amp; Dwyer Pub., 1991), 119-59.</bibl>

Here’s an example of what it will look like on the website (note that the double source is number four):

Multiple and repeating citations

We don’t use short forms of sources when they repeat since it’s less work to simply copy/paste the reference. Note that we don’t include the pop-up content in the example below. It’s presumed that the notation numbers are added correctly.

<listBibl>
   <bibl xml:id="shrapnel_b_1">1. <ref target="cdc:B606S01">Shrapnel to Newcastle</ref>, 4 April 1860, 3586, CO 60/9, 386; <ref target="cdc:B606S02">Shrapnel to Newcastle</ref>, 5 April 1860, 3872, CO 60/9, p.388.</bibl>
   <bibl xml:id="shrapnel_b_2">2. <ref target="cdc:B606S02">Shrapnel to Newcastle</ref>, 5 April 1860, 3872, CO 60/9, 388.</bibl>
   <bibl xml:id="shrapnel_b_3">3. Ibid.</bibl>
   <bibl xml:id="shrapnel_b_4">4. <title level="a">
         <ref type="external" target="https://www.warmuseum.ca/supplyline/wp-content/mcme-uploads/2014/10/CWM_SupplyLine_ShrapnelBullets_EN_FINAL_20140922.pdf">Artifact Backgrounder: Shrapnel Bullets</ref>
      </title>, <title level="m">Canadian War Museum</title>; John Sweetman, <title level="a">
         <ref type="external" target="https://doi.org/10.1093/ref:odnb/25473">Shrapnel, Henry</ref>
      </title>, <title level="m">Oxford Dictionary of National Biography</title>.</bibl>
   <bibl xml:id="shrapnel_b_5">5. Ibid.</bibl>
   <bibl xml:id="shrapnel_b_6">6. John Sweetman, <title level="a">
         <ref type="external" target="https://doi.org/10.1093/ref:odnb/25473">Shrapnel, Henry</ref>
      </title>, <title level="m">Oxford Dictionary of National Biography</title>.</bibl>
   <bibl xml:id="shrapnel_b_7">7. Ibid.</bibl>
</listBibl>

Abstracts

Abstracts are brief summaries of individual despatches, as well as the minutes, enclosures, and other documents that occasionally accompany them. Abstracts are helpful research tools that give viewers a sense of the main topics of a given despatch and allow them to see if it aligns with their research or interests without having to read the entire despatch.

Abstracts are notoriously difficult to write because they require a close reading of the documents, an understanding of their relevance to the collection as a whole, and their historical importance. Abstracts are highly subjective: what might seem important to one of us might not be to others on the team. It is important that we work together on the more complex documents, or whenever we have doubt about what to include, or not, in our summaries.

There are two ways to access the abstracts on the Colonial Despatches website:

1. Select the ‘browse’ link in the main menu, where the despatches are ordered by year, and continue to navigate to a despatch of a specific date:

2. Select the ‘Abstract’ link at the top of a given despatch:

Required skills

This section assumes that you have knowledge of the following:

- How to tag content.
- How to use the SVN repository, that is, commit your changes to the database.
- A detailed understanding of the Colonial Despatches website and its various sections.
- Familiarity with the structure and elements of a transcribed despatch as it appears on the Colonial Despatches website, as well as the minutes, enclosures, and other documents that accompany it.
- Proficiency in Oxygen (XML editor)- and a firm knowledge of the code and tags you will use during the markup process.
- An intermediate to advanced knowledge of 19th-century BC history.

Writing abstracts

Use Google Docs to draft your abstracts and share this document with your fellow editors, and ensure that they have permissions to edit the file. Darth Google is evil, but Google Docs allow for comments and feedback across platforms and editors. If you don’t know how to work in Google Docs, then consult your Despatches colleagues who do.

As with all writing for this project, it’s essential that you take a look at the Style Guide section of this document before you begin. But we also have a special abstract style guide below as well with some more specific conventions.

Before you write abstracts

Read the content (!)

It’s very important to read the entire despatch, as well as the attached minutes, enclosures, and other documents, before you attempt to write your abstract. Because certain topics tend to be the subject of multiple despatches, it’s helpful to read the abstracts of the preceding despatch (or despatches) and, if time permits, those of the previous year, in order to give you a better understanding of the topics of your current despatch.

After you have read the despatch and all attached minutes, documents, and enclosures, you may want to go through them again and take notes in order to get a basic framework for your abstract. It’s a good idea to write the first draft of your abstract on Google Docs and then copy/paste your content into the XML file once you or a Despatches colleague has proofread it.

Audience and voice

The target audience of the Colonial Despatches website is students, teachers, Indigenous scholars, professors, researchers, other members of the academic community, history buffs, and lawyers.

As an academic site, all original written work, whether it be abstracts, biographies, and vessel or place entries, should be written to university-level academic writing standards. Concision and clarity are key. The main goal of an abstract is to summarize despatch content with a purpose to inform, so please refrain from personal comments or observations—this can be the most difficult part!

Remember that the role of the abstract is to describe what is being communicated, not what you or anyone else thinks about the communication. Think of yourself as a reporter, describing what you see.

For voice, please apply the following:

- Use present tense. For example, use “Douglas relates concerns about funds for roads,” and not “Douglas related concerns.”
- Avoid passive voice. For example, “Douglas instructs the HBC to sell their Victoria properties,” and not “The HBC is instructed by Douglas to sell their Victoria properties.”
- Avoid gerunds. Gerunds are formed by adding “-ing” to a verb, for example: “sleeping,” “drawing,” “swimming.” But, they are not the “-ing” verb forms that you see in the present or past continuous tense. They look the same, but gerunds are actually verb forms used as nouns. We avoid them because they can cause confusion, especially in cases where a gerund could be mistaken for a participle.
- Concision reigns. Please read this Purdue Writing Lab page on Concision and Dr. Kim Bank’s Wordiness, Wordiness, Wordiness List, bookmark the latter.
- Repeat names to avoid confusion. For example, we could write that “Lytton informs Douglas that his wig is, like, so eighteenth-century,” but it is not entirely clear as to whom the “he” refers. In cases such as this, please repeat the name: “Lytton informs Douglas that Douglas’s wig is, like, so eighteenth-century.”
- Finally, write something that you would actually want to read.

Word count

The word count of an abstract will vary with the length of the despatch. In most cases, use one paragraph for all content; however, if you have particularly long documents, then you may need to write multiple paragraphs.

Smaller despatches should require only a few sentences. The word count for abstracts of large despatches should not exceed roughly 200 words—anything over 200 words likely requires revision. As for every rule, we expect exceptions, so if you’re stuck, or unsure that you have captured the nature of the correspondence, please re-read the document(s) to see if you can omit anything and still retain the main topics and overall purpose for the correspondence. When in doubt, consult your colleagues.

Despatch structure walk-through

Colonial Despatches correspondence often contains three types of communication: (1) the original despatch or letter, (2) minutes, and (3) attached documents (enclosures or other files).

The following sections discuss what to include from each part of the correspondence file:

The despatch, letter, or main correspondence

Include the following, where applicable, in your abstracts:

- In the first sentence, include the author of the correspondence and the topic(s) of the communication. (For further writing instructions see the Abstract Style Guide)
- You may include other people, places, and subjects, important to the correspondence, thereafter.
- In a strange quirk of fate, the longer documents are often easier to summarize than the shorter ones. Consult your Despatches colleagues as needed.

The minutes

We indicate to the reader already the number of minutes in a given correspondence.

Typically, we ignore minutes that discuss administrative procedures, such as “Put by,” or “Send to Treasury.” However, should the minutes contain discussions, decisions, or content of importance or of note, then please summarize them as you would an original correspondence.

If you do include minute correspondence in your abstract, you can consult Gord's list of Colonial Office staff and consultants, which is roughly ordered in a hierarchy of the positions and who held them when, to get a better sense of who may be instructing whom and when a staff member may likely be asking a question even though they make no use of a question mark. Currently, it can be found here.

Enclosures and other files and attachments

We indicate to the reader already the number of attached documents in a given correspondence.

“Enclosures” are documents enclosed with the main document. “Other files” are included in the file or are associated with a given correspondence, but aren’t considered part of the enclosures. For example, let's say a despatch encloses a list of land owners on Vancouver Island. The Colonial Office receives this correspondence, makes notes all over it (minutes), and sends it on to the Treasury, but, for the sake of reference, adds a map to the file. The list of landowners would be the “enclosure,” but the map would be an “other file.”

Jim's team designated whether or not given correspondence was either an “enclosure” or an “other file,” and this convention is reflected in the tags we use to designate each in the XML code. These codes are <div type="enclosure_entry"> and <div type="other_entry">, respectively.

Sometimes, “enclosures” can be misidentified as “other files,” and vice versa. To get around this issue while describing the “enclosure” or “other file,” we use “document” as a catch-all term. A “document” could be an “enclosure” or an “other file,” so we're covered in terms of accurate language, without having to go back to the file later and make corrections should, say, an “enclosure” turn out to be an “other file,” or the reverse.

As a general approach, if the enclosures/attachments reflect the correspondences' content, then we will ignore them in our summaries. In this sense, we assume that readers who see, say, that a letter has 5 enclosures, will expect to find that the enclosures pertain to the letter’s subject. However, if the enclosure/attachments are somehow very different in subject, and interesting to you, or provide further context to the historical significance of the despatch, then mention them.

For the enclosures and other files, use an opener such as “One of the included documents…” or “Included documents describe…”

In other words, keep it active, keep it safe. And, if anything above seems unclear, please consult your Despatches colleagues.

Transcribed enclosures and attachments

The number of transcribed documents will be listed in the header metadata. Therefore, it is not necessary to make any special mention of transcribed enclosures. Treatment of these will fall under same guidelines and untranscribed enclosures. If the enclosed or attached document is of significance and adds to the reader's unserstanding of the despatch, a brief description of its contents makes sense. If not, the enclosure can be ignored.

How to incorporate quotes from the correspondence

Think of the abstracts as miniature essays, and incorporate quotes as you would for a university paper. In other words, put quotation marks around anything you pull, verbatim, from the despatches! Here is an example. In this despatch, Douglas writes the following:

“I am happy to inform your Lordship that nothing has occurred to disturb the tranquility of the Settlements on this Island”

If we summarized this line as follows:

Douglas reports to his Lordship that nothing has occurred to disturb the tranquility of the settlements on Vancouver Island.

then, we would miss some necessary quotes, which would be added as follows:

Douglas reports to his “Lordship” that “nothing has occurred to disturb the tranquility of the Settlements” on Vancouver Island.

Quotes can serve a handy purpose when it’s difficult to discern exact authorial intention or meaning, or when the writer's phrasing is necessarily specific. Take the following example from Lord Grey's minute in this document:

“It is better simply to say that I do not consider the charge to be one [which] ought to be borne by the public.”

We could say that “Grey does not want taxpayers to bear the cost,” but this statement is open to debate. Does he refer merely to the British tax base? Or, does he refer to some other body? Would this be a colonial-only cost? It could take considerable time to tease out exactly what Grey means, and heaps of research. This is all well and good, but we’re supposed to be writing abstracts, not following semantic breadcrumbs, seductive as that is. So, why not let Grey speak for himself, in all his potential ambiguity? We could write the following:

Grey does not want the cost “to be borne by the public.”

Remember abstracts summarize, not speculate. What Grey writes is the most accurate representation possible. The incorporation of quotes takes time to master. Be patient, and if you are unsure, then consult your Despatches colleagues!

*Note: It is not necessary to quote words provided by other members of the project if you include them in your abstract. We are all on the same team! This means that you may use your colleagues' descriptions of significant enclosures in your abstract without the use of quotation marks.

Abstract style guide and edicts

These are resolutions determined by the Despatches team in 2020.

- Write out Colonial Office (instead of CO) or any abbreviations that are not easily understood.
- Write out first instance of words commonly abbreviated (examples: British Columbia and Vancouver Island) and use abbreviations thereafter.
- Try to work against the compulsion to make a case or argument in the abstracts: these are summaries, not analytical papers. Do not editorialize. (Historians on the team can let go of the compulsion to show-off every cool quote they found. It’s the readers job to find the quotes.)
- Avoid verbs that *read into* what you see as the motivation for the document. Tell it like it is, not what you think it to be. If you're using a verb that puts you in the writer's head, then you're off track from a summary and on track for a novel. We cannot know what is in another person's mind. Here's a short list of “neutral” versb:

- relates
- conveys
- notes
- describes

Also see Janelle's list of Critical Verbs for some other suggestions.
- Related to above we have placed a moratorium on the verb “writes,” because, like, duh. Typically, Colonial Officials and people contacting the office do the following:

- acknowledge
- confirm
- instruct
- request
- report
- explain
- relate
- refer
- transmits

*Note: We do not quote these “verbs” unless they are germane to the intention of the letter in some special way. You may use quotes in cases where the verb is either uncommon or totally badass in terms of interest to modern readers.
- We are begrudgingly okay with using “minutes” as a verb, or a noun, in order to avoid the wordy and repetitive and lengthy clause of “In the minutes…,” but we need to show the reader the content's origins, in the artifact sense. For example, “Blackwood minutes that Douglas's canoe trip was necessary,” or “Blackwood's minute to Carnarvon reports that Douglas has received funds for supplies.” Some Colonial Office common action scenarios:

- Recommendations: Blackwood's minute recommends…, or, Blackwood minutes to Carnarvon that he recommends...
- Authorizations: Blackwood's minute authorizes…
- Confirmations: Blackwood's minute confirms…

- We no longer feel the need to always mention recipients in the opening of the abstract because senders and receivers appear in the header metadata. Mention recipients only in cases where disambiguation is required.

Reviewing the process

If you feel bogged down by the above details and expectations, remember that the abstract is supposed to provide a helpful summary of the correspondence, and so your overall aim is to do the following:

- Summarize the salient points of the original correspondence.
- Mention any minutes particularly relevant to the original correspondence.
- Mention any enclosures or attachments that provide further context to the original correspondence or the document’s significance to the history of BC.
- Last step, please record that you have commited a marked up version of the abstract in XML in our ColDesp Abstract Project Tracker. Find the id of the despatch you added the abstract to and fill out the "in XML (NEW)" cell with "Yes" and "(Your Initials)":

Note that most of the new abstracts won't have an entry in the "OLD" column, which is to be expected. Phase 2 will be to update the old ones, time and resources permitting. In your Google doc, you can also, add a token, "PUBLISHED" to your Google doc entry = [PUBLISHED date-of-entry(ISO)].

Examples

Examples from a range of abstracts:

1. Simple correspondence, no minutes or enclosures: B64006 V667703

2. Simple correspondence with mentions of minutes/attachments: B67013CO V645FO02

3. Complex (long) correspondence with mentions of minutes/attachments B67013 B67022

Tagging abstracts

Below is an example of a tagged abstract, and where it should be placed within the <teiHeader>.

<encodingDesc>
   <styleDefDecl scheme="css"/>
</encodingDesc>
<profileDesc>
   <abstract>
      <p>On behalf of <name key="russell_j">Lord Russell</name>, <name key="layard">Layard</name> forwards to the Under-Secretary of State a letter from the Belgian Minister at <name type="place" key="london">London</name> in which the minister enquires about the “fate” of <name key="noiset">Noiset</name> who was last heard from while living in <name type="place" key="victoria">Victoria</name>. <name key="elliot_tf">Elliot</name>’s minute authorises <name key="blackwood_aj">Blackwood</name> to forward the inquiry to the Governor of <name type="place" key="vancouver_island">Vancouver Island</name> and to inform the <orgName key="foreign_office">Foreign Office</orgName>.</p>
   </abstract>
</profileDesc>
<revisionDesc>
   <change resp="lyallg" when="2020-03-16">Added abstract.</change>
   <change resp="lyallg" when="2019-04-10">Inserted revisionDesc.</change>
</revisionDesc>

In the example above, there are few things to pay close attention to:

- Always add your netlink id or equivalent identification to an @resp in a <change> tag within the <revisionDesc> with a date and a text value of "Added abstract."
- The abstract is placed inside the <profileDesc> tag. If that tag doesn’t exist, you’ll have to create it. It appears after the <encodingDesc> tag within the <teiHeader> tag.
- Tag the abstract's content just as you would the correspondence. That is, be sure to tag people, places, and vessels in the abstracts (as long as the instance of each already exists in our database), as well as dates. See the mark-up guides for people, places, vessels, organizations, and dates, for details and tips.

IMPORTANT: once you’ve committed your abstract to the database, make sure to go online to proofread your work, and ensure that all links work as they should.

Update the ColDesp Abstract Project Tracker and add [PUBLISHED 2020-03-03] note in your Google doc.

Troubleshooting abstracts

Letterbook copies versus originals

Some documents in the collection appear as both letterbook copies and originals. For example, V597067 is the letterbook version of B597067. Notice that the letterbook version is written on lined paper and often contains abbreviations (like "B.C.") as opposed to the original, which is not on lined paper and has words typically spelled out in full. In these cases, add abstracts to the original versions, only. Also, write a statement in the abstract, as a separate paragraph, to indicate that this is a letterbook copy, and point to the original despatch with a <ref> tag:

<div type="despatch_from_london">
   <p>This document is a letterbook copy of <ref target="cdc:B597067">B597067</ref>. </p>
</div>

Correspondingly, add a statement in the abstract of the original document:

<div type="despatch_from_london">
   <p>See <ref target="cdc:V597067">V597067</ref> for a letterbook copy of this document.</p>
</div>

*Note: be on the lookout for any instances of originals or letterbook copies that do not point to each other in their respective abstracts. As ever, if you are unsure about any of this, please consult your Despatches colleagues.

Adding descriptions to enclosures and other files as needed

In addition to the designation mentioned above, Jim's team also summarized the content within most of the enclosures, and other files. However, some enclosure or other- file summaries may contain merely an author, an addressee, and a date. For example, “Douglas to Lytton, 1 March, 1848.” In these cases, we review the image scans of the document in question and summarize it ourselves below your Google doc abstract. Make a note “SUMMARY NEEDED” above your new summary so that it is easily identified or found by other Despatches team members if necessary. We then add our summary to the XML file, as part of the existing list of enclosure or other-file descriptions. Add this new content to the original summary from Jim's team. This means adding content at the bottom of the XML file as well as in your abstract and marking both up. Note that we will also need to go back and fix earlier abstracts and other file entries that have not added content and mark-up.

People

The biographies appear in pop-up windows in a given despatch. Their purpose is to enrich readers' sense of a given despatch by providing historical context.

In general terms, the biographies need a lot of work. It would be a project in itself to finish them all. As of this writing, nearly 1,500 have no content, and nearly 250 need more revision or content.

We also inherited some biographies, mostly for 1858 from Jim’s team back in the 80s. These bios don’t conform to our footnote style, and so at some point we’ll have to dive in and edit them. See the “Edits to inherited biographies” section below.

Writing biographies

Our biographies try to present a given historical figure in the context of their role as described in the despatches. The following list provides general expectations for a given biographical entry:

- Information relevant to the colonies of Vancouver Island and British Columbia is of primary importance and should be presented first.
- Frame the person within their role as mentioned in the despatches.
- Birthplace and death (in the xml file, insert information inside “birth when” and “death when” tags at the top of each bio).
- And, should the information be available…

- Some personal background
- Some educational background
- Some professional background
- A choice tidbit, should one emerge

- In the absence of other source material, use the despatches. For example, in a recent entry for Shahoowha, for whom we could find nothing else, we wrote the following: “Shahoowha was a Chief of the Nisga’a people. His name appears in the despatches as one of the Nisga’a Chiefs who signed an agreement ‘to deliver the property taken from the Schooner “Nonpareil” in October 1861.’ The agreement was made in response to ‘a robbery of goods…by the Nishka Indians, at Nass River.’ The conflict was reported to be fuelled by ‘Drunkenness’ however, the Nisga’a stated that ‘the master’s account of the goods taken [was] much exaggerated.’”

Content, structure, and voice

There’s no definite prescription here, except to try and keep it concise and relevant. Two to three paragraphs, or roughly 250 words, is a good length. If you have a compelling narrative, who could blame you if you go over the word count? But make sure you keep it lively. The bio will appear in a pop-up box, so consider what length seems appropriate, and what you would be willing to scroll through if you were on the site. The intended audience is secondary and post-secondary readers and scholars. That said, try and have some fun with it. After all, would you want to read a boring biography? Please read the Style Guide section before you write anything.

When possible, information relevant to Vancouver Island and British Columbia should appear within the first couple of paragraphs. Remember, it’s important to frame the person within their role as it appears in the despatches. Try to include some personal, educational, and professional background information. Balance hard facts with interesting tidbits, or quotes, that illuminate the person’s character or experience.

To keep track of your sources as you draft, note your citations at the end of each sentence in brackets (1). Alternatively, you can use the footnote function in Google Docs and then add the brackets once you’re finished the editing phase so that footnote numbers translate easily to the XML document. At the coding phase, you’ll need to create a list of your sources in a separate paragraph. This process is covered in the Tagging People and Biographies section.

Biography research

The Colonial Despatches website aims to be an academic resource, so please use academic sources for your research, particularly on the web. Wikipedia is a fine starting point, but if you’re unable to find that information in another verified source then we can’t use it. In these instances, you can make a note within the biography XML file that links to the webpage. This way, future researchers will know what, if anything, has been done for this bio, and will have a place to start.

When you begin your research it’s best to check the XML file for any notes that were left. To find these notes, go into the appropriate file where your figure’s biography template is located. Any notes will be commented out in a <note> tag like in the example below:

<person xml:id="wade_j">
   <persName type="unavailable">
      <surname>Wade</surname>, <forename>John</forename>
   </persName>

</person>

See Research Resources for a list of frequently used sources. To verify names, you can check the lists of ship passengers from local newspapers in port cities. If you find yourself stuck, please consult other members of the Despatches team. There are many e-books available online, particularly when researching people with peerage titles; most e-books are considered a valid resource, but if you have questions, please consult your colleagues.

Additionally, there are great subject guides for Victoria and Vancouver Island from the UVic libraries. A good book to consult, particularly in dealing with people and place names, is Captain John T. Walbran’s British Columbia Coast Names. We keep a copy in the office, and it’s available in the library, call number: FC3806 W35 1971a.

IMPORTANT! If you are unable to find any outside information, please construct a short biography based on the information available in the correspondence. After all, something is better than nothing, and we can always add more content later, should a reliable source for a given name suddenly appear.

Example bios and a bit about them

These examples are meant to give you a taste of the “biodiversity” we currently have. Don’t get hung up on trying to recreate them!

- See Grant, Captain Walter Colquhoun (1822-1861) for a long bio that summarizes well from a single, external source: the Oxford DNB. This one also uses the despatch references well.
- See Gough, Lieutenant General Lord Viscount Hugh (1779-1869) for another long-form bio.
- See Adams, John R. for a bio that is, arguably, around the ideal length, and it opens with content immediately relevant to the Despatches collection.
- See Alcalá-Galiano, Officer Dionisio (1762-1805) for a long bio written on a rather well-known historical figure. This bio uses multiple sources, both book and digital.

Edits to inherited biographies

Many of the inherited biographies require heavy editing, particularly in the B58_bios.xml file. For a start, please apply our style to citations, spelling, and numbers (see the Style Guide section). Please update language where needed, especially terms for Indigenous Peoples. If possible, do some research to determine the particular Indigenous person or group mentioned, and please consult supervising members of the Despatches team when you encounter questionable markers of Indigeneity.

Some of these bios are rambling behemoths, so please prune, trim, and reorder them so they’re more concise and relevant to the despatches. Also, be sure to keep an eye out for missing or misplaced tags for people, places, and vessels. Once the critical changes are complete, check if the names in B58_bios.xml need to be placed in the file for a different year.

XML mark-up for bios: getting started and workflow

Finding a person

First find your person by searching for the @xml:id of the person in the xml/bios folder by right-clicking on bios and doing a search/replace on the directory. For example, if we wanted to find Joseph Cahill we would do a search for "cahill_j" in all lower-case with Case sensitive toggled on.

Finding Joseph Cahill

Adding birth and death dates

Now that we have found the person you can uncomment the birth and death elements by hitting 'Ctrl'+'Shift'+',' and add the dates. (For Mac users it is: Cmd + shift + M)

<birth> and <death> elements commented out.

<birth> and <death> elements have been uncommented with dates filled in.

A couple notes: (1) if you only know a year or a year and month, that is fine, just add that information and delete the zeros for the day; (2) if you don't have a birth or death date just leave the element commented out.

Adding bio content

Add your bio content by copy and pasting it into <p> elements in the <note> element. Every paragraph goes in its own <p>.

Content added to bio

Adding end notes

Now add your endnotes. In another <p> tag create a <listBibl> element and within that element add your first <bibl> entry with the number "1." which is your first note. Then add a @xml:id to the <bibl> using the formula outlined in 7.2. Notation Numbers. For how to mark-up your citation see 7.3. Basic Endnotes.

One tip: you can copy and paste all the code from the examples and replace the values with your own information, author, title, url, etc.

Added endnotes with @xml:id. Examples are of an online dictionary and a book citation.

Linking endnote indicators with their corresponding note

To link your indicators with their note we will replace the current indicators (in parenthesis if you formatted them as they are formatted in this example) with this code:

<bibl corresp="#xml:id_b_corresponding number here"><hi style="vertical-align: super; font-size: 80%;">number goes here</hi></bibl>

Copy and paste this code replacing your first indicator “(1)”. In the @corresp, after the “#” add the @xml:id of your first endnote and replace the text “number goes here” with the number of the note. Repeat this step until all your indicators are replaced with a fully marked-up number.

Original plain text indicators to be replaced.

Indicators with full mark-up including @corresp linking to the endnote.

Marking-up content

Back to your content…you will need to mark-up all the people, places, vessels, and dates. People, places and, vessels get <name> elements see 9.2.1.2. Steps to tagging names (for newbies), 10.2.1. How to tag places that appear in the correspondence files, and 11.2.1. How to tag vessels that appear in the correspondence files, for details. For tagging dates see 5.8. Date Tags and 5.8.3. Ranges, with from and to.

Or you can consult this example:

Marked-up bio.

Note: do not tag the person whose bio you are writing. This is unnecessary.

Recursive tagging

This issue, depending on the pop-up in question, is a both a style and coding concern. As a general rule, do not tag references to the entry you are already reading. This is true for bios, places, and vessel entries.

For example, in James Douglas’s bio, you need not tag the name “James Douglas,” as this would be recursive—in other words, refer back to the referent—and redundant, as you’re already reading about James Douglas to start with.

Do tag all other references as you would in a despatch. For example, if Douglas's bio refers to Lord Grey, then tag Lord Grey accordingly, as this is an entry external to the Douglas bio.

Final steps

Finally, erase the @type="unavailable" or @type="incomplete". And add your initials in a comment with a date indicating that you wrote the bio (credit for your work!).

Pointing to @type="unavailable.

@type="unavailable is erased and writing credit comment added.

Make sure you check that your document is valid, save it, and commit it on the svn repo.

Tagging people and biographies

Tagging people in the correspondence

This section deals with how to tag mentions of people in the letters. This task breaks down into two parts: (1) tagging people already in the database, and (2) adding new names to the database. This section assumes that you are already familiar with the basics of tagging. If not, then consult a Despatches colleague.

Tagging people already in the database

What we mean by “already in the database” is that the name for the person in question has already been added to the biographies files, and that the name can be found on the website. You can find all the names ever added for all years on the biographies index page.

Steps to tagging names (for newbies)

- Confirm that the name you need to tag is already in the database by going to the biographies index page.
- Once you have confirmed that the name is already in the database, you will need to know the person’s key value, or unique ID. In the following example, the unique ID is in quotation marks: <name key="grey_hg">

- To find a person’s unique ID on the biographies index page hover your mouse over the name and a pop-up will reveal the unique ID, like magic!

- Back in your XML document, it’s time to tag the name.

- Highlight/select the name
- On the keyboard, hit Ctrl + e and a pop-up will appear
- Type “name” (without quotes) into the pop-up, then click the “OK” button. This will wrap your name in an open and closed name tag. NOTE: as soon as you type “n” the autocomplete options will appear, and you can select “name.” At this point, you should have something that looks like this example: <name>Earl Grey</name>

- Add the @key="" attribute after the open <name> tag, as in the following example: <name key="XML_ID_here">Earl Grey</name>
- Add your unique Id for the name between the quotes in the "key=""" attribute, as in the following example: <name key="grey_hg">Earl Grey</name> All done! You now have a fully tagged name.

Name tagging practices

- When you tag names in the correspondence, never add space between the tags and the name. For example:

- Wrong: <name key="grey_hg"> Earl Grey</name>
- Wrong: <name key="grey_hg">Earl Grey </name>
- Right: <name key="grey_hg">Earl Grey</name>

- Tag the name only, even in the case of possessives. For example, in the case of “Earl Grey’s letters,” the tag would wrap around only “Earl Grey,” as in <name key="grey_hg">Earl Grey</name>'s letter.
- Tag “Mr.” and its variants if it’s part of the name, as in <name key="blackwood_aj">Mr. Blackwood</name>.
- DO NOT tag “Esquire” and its variants, such as Esq., Eq., Esque., and so on.
- DO NOT tag names in notes, footnotes, bibliographic information, or any other content clearly separate from the correspondence. Also, do not tag the name of the person whose bio you’re marking up. Ask your Despatches colleagues if you’re uncertain about whom to tag.
- You can wrap a name tag on titles, but only in cases where clarity is required. Otherwise, do not tag them. For example, a paragraph might refer to Blanshard and Douglas, who were both governors, and say something like, “Blanshard and Douglas both liked crumpets for breakfast.” But, “the governor born in the Caribbean preferred his with jam.” This is obviously a very rare scenario, but in this case we would tag “the governor” as Douglas in this case, for purposes of disambiguation. But, when in doubt, leave it out, or consult your Despatches colleagues as needed.

Adding new names to the database

This section presumes that you have access to the biography XML files, and that you already know how to tag names.

IMPORTANT: Before you add new person to the biography files, make sure that they don’t already exists in the database! Not sure? Check the the biographies index page.

As a rule, we always tag/add people mentioned in the correspondence. That is, names that occur in the text of the transcribed correspondence. Of course, there may be other names tucked into the non-transcribed enclosures, letters, and other files, but we have neither the time nor resources to investigate them further.

The biography files are located in the “bios” folder (files path …/xml/bios). You’ll notice that there are multiple bios files, with file names such as V46_bios.xml and V60_bios.xml. The “V” in the filename stands for Vancouver Island colony, and the number represents the year. We break the bios files into separate years for two reasons: (1) if all the names were in one, huge XML file, it would take too long to load, and (2) we can have several people work on several different files at once without running into file version conflicts.

- Open the appropriate biography file in Oxygen.

- NOTE: we add the person to the file for the year in which the person was first mentioned. For example, Captain Duntze appears in letters spanning several years, but he’s mentioned first in an 1846 letter, so his entry appears in the 1846 bios (V46_bios.xml).
- If there isn't already an alphabetized section (based on the first letter of the surname) then you need to add one. Let’s pretend that the new name is Peter Parker. First, we add a comment tag, as this is a handy separator: <!-- PPPPPPPPPPPPP -->. Below the tag, we add a <personGroup> tag with the appropriate value: <personGrp xml:id="P"/>. Here’s an example of what it actually looks like in Oxygen: <personGrp xml:id="P"/>

- Choose an appropriate @xml:id for your new person. In the example below, the unique ID, or name value, is in quotation marks: <person xml:id="duntze_ja"/>

- NOTE: Choose a unique ID of the shortest possible length based on the last name of the person. For example, let’s say you have someone name Constantine Rutherford Gonzoplix. Chances are there is no other person named Constantine Rutherford Gonzoplix, at least in this dimension, so you’re safe to create a unique ID from the last name only, as in <person xml:id="gonzoplix">. However, if you find yet another “Smith,” then you will likely need to incorporate the initials into the unique ID, as in <person xml:id="smith_jp">. As always, if you’re unsure about any of this, consult your Despatches colleagues.

- Add a comment tag, with your initials and the date, so we know who wrote the entry, and when. Add your comment tag after before the <persName> tag, as in this example:

<person xml:id="duntze_ja">
   <persName/>
</person>

- We have a shortcut key to create a new bio placeholder. Press Ctrl Alt 1 (on Linux or Windows OS). Below is an example of a bio template. Note that this is a placeholder bio, one to which we have yet to add content the cursor will sit waiting for a new unique @xml:id:

<person xml:id="${caret}">
   <persName type="unavailable">
      <surname/>, <forename/>
   </persName>

   <note>
      <p/>
      <p>
         <listBibl>
            <bibl>1. </bibl>
         </listBibl>
      </p>
   </note>
</person>

- Biography tagging practices:

- The name tags must be entered in the following order: <surname>, <roleName> (if applicable; see below), then any <forename> tags. Always place commas directly after the closed </surname> tag, and in no other place. If you have only a surname, then don’t add a comma.
- Example with comma:

<persName>
   <surname>Ebden</surname>, <forename>Richard</forename>
</persName>

- Example without comma:

<persName>
   <surname>Ebden</surname>
</persName>

- On <roleName> tags, the TEI writes the following: “<roleName> contains a name component which indicates that the referent has a particular role or position in society, such as an official title or rank.” Here’s an example:

<persName>
   <surname>Ebden</surname>, <roleName>Sir</roleName>
   <forename>Richard</forename>
</persName>

- Some <roleName> examples include Governor, Lieutenant, Sir, Lord, Earl, Justice, Reverend. With this in mind, “Mr.” is not considered a role, as such, nor is “Mrs.” If the person in question has no “role” as defined above, then do not add the <roleName> tag to the entry.

- @type="incomplete," "complete," and "unavailable" bios are attributes that are added to indicate the state of a biography’s completeness. When a biography is incomplete, we need to track this for statistics purposes, and for easy searching. The attribute is added to the <persName> tag.

- "incomplete" is used when content exists, but it’s unfinished or inadequate, and will be rewritten in future: <persName type="incomplete"/>
- "unavailable" is used when no content has been written yet: <persName type="unavailable"/>

- When a biography is complete, neither of the above attributes should appear.

- <birth> and <death> tags are commented out until we know either or both, as in the following example:
- Once you know the date(s), fill in the year/month/day (or just year/month, or simply year) and remove the comment tag(s). <birth> and <death> tags with certainty, or @cert attribute, are used to alert the read that we aren’t entirely certain that we have an accurate birth or death date. You have three value options with a @cert attribute. Here’s what it looks like in code form:

<birth when="1765" cert="low"/>
<birth when="1765" cert="medium"/>
<birth when="1765" cert="high"/>

Biography markup for citations

See the Basic Endnotes section.

Places

Writing “placeographies”

These instructions assume that you have already read several placeographies, and that you have at least a passing interest in the subject!

As with biographies and vessel entries, website readers can click on a place’s name to learn about it. Places appear as mentioned in the letters, but readers can view all the placeographies as a collection on the places index page.

The following is a working list of things to consider for your placeographies:

- Keep it brief, aim for roughly 200 words.
- In the first sentence, provide the relative location of the place, as in the following examples:

- American Bar is located along the Fraser River’s eastern bank, roughly 6 km above Hope.
- Cape Mudge is located on the south end of Quadra Island, which lies off the eastern coast of Vancouver Island.
- The Stikine River flows southwest out of Stikine Plateau through Northern BC and the BC-Alaska boundary.

- Provide the origin for the place’s name.
- When possible, provide the Indigenous name and name origin.

- TIP: Most First Nations groups have websites these days. Be sure to check these in order to get the latest spellings.

- We honour special characters for Indigenous and First Nations names. For example, we write Hawaiʻi with the ʻokina, not an apostrophe.
- Provide a given place’s historical significance, ideally with respect to local history.
- Feel free to incorporate quotes or information about a given place from the Despatches collection.
- Add any fun or significant facts you can find. If you’re not sure about whether or not to include something, consult your Despatches colleagues.
- See Research Resources for a list of good sources to begin with.

Here’s an example of what a completed places entry looks like, as taken from the indexes page:

Tagging “placeographies”

How to tag places that appear in the correspondence files

This one is pretty straightforward: wrap the correct tag around it. <name type="place" key="vancouver_bc">Vancouver</name>

If you need the unique ID of a given vessel (the “key=” value) refer to the places index page. Hover your mouse over a given place’s name and its key value will appear. The same is true for people and vessels.

How to add a new place to the database

This process is, more or less, the same for adding newly discovered people to the database. See the Adding new names to the database section for details. Note that unlike the biographies, which have separate files for each year, the places are all in one big file!

Placeholder template for new places

Note that this is a placeholder only, one to which we have yet to add content. The short-cut key for this template is Ctrl Alt 3.

IMPORTANT: “Un-comment” things later as you add the necessary content, specifically the <location> tags and the <desc> tags that contain your content and bibliographic information, respectively.

<place xml:id="${caret}">
   <placeName>NAME</placeName>
   <location type="path">
      <geo/>
   </location>
   <desc/>
   <desc>
      <listBibl>
         <bibl>1. </bibl>
      </listBibl>
   </desc>

</place>

NOTE: As ever, if you're unsure as to what a complete placeography looks like, go to the places file ([…]/xml/places/places.xml) and look at a completed entry!

How to tag placeographies in the places.xml file

We store and place new entries in an XML file called “places.xml.” The following is an example of a completed entry in XML format:

<place xml:id="birch_bay">
   <placeName>Birch Bay</placeName>
   <location>
      <geo>48.895159 -122.789767, 48.894745 -122.784574, 48.897412 -122.778117, 48.900577 -122.774573, 48.903075 -122.771535, 48.905907 -122.767357, 48.906740 -122.763684, 48.907573 -122.758871, 48.909905 -122.752664, 48.914401 -122.748231, 48.918730 -122.745824, 48.923976 -122.745444, 48.929887 -122.745950, 48.933801 -122.748865, 48.936798 -122.752541, 48.940711 -122.761161, 48.942541 -122.769655, 48.931378 -122.787392, 48.931710 -122.791955, 48.894492 -122.793313, 48.895159 -122.789767</geo>
   </location>
   <desc>Birch Bay is located just south of the Canada-US border in southeastern <name type="place" key="georgia_strait">Georgia Strait</name>. To the west, across the Strait from the bay, sits the southern <name type="place" key="gulf_islands">Gulf Islands</name>. In 1792, <name key="vancouver_g">Vancouver</name> anchored in the bay, and was inspired to name it in reference to the abundant birch on the bay’s shores; the Spanish knew it as Ensenda de Garzon.<bibl>
         <hi style="vertical-align: super; font-size: 80%;">1</hi>
      </bibl>
   </desc>
   <desc>According to George Davidson, a British painter on <name key="vancouver_g">Vancouver</name>’s expedition, one of the Indigenous names for the bay was, in Davidson’s Anglicization, “Tsan-wuch."<bibl>
         <hi style="vertical-align: super; font-size: 80%;">2</hi>
      </bibl>
   </desc>

   <desc>
      <listBibl>
         <bibl>1. Lynn Middleton, <title level="m">Placenames of the Pacific Northwest Coast</title> (Victoria: Elldee Publishing Company, 1969), 23.</bibl>
         <bibl>2. Ibid.</bibl>
      </listBibl>
   </desc>
</place>

Note that between the <place> </place> tag (the tag that contains the whole entry) <p> tags are invalid. So, we use a <desc> (description) tag instead. If you want multiple paragraphs then use multiple <desc> tags.

How to add <location>/<geo> tags

Each placeography should include a map link. This link takes readers to the Google Maps location for a given place.

We have to add geo coordinates manually, see How to acquire coordinates for instructions. Geo coordinates are literally the longitude and latitude values for a given point, or waypoint, in decimal degrees.

The <location> tag, which contains the <geo> tag, is placed after the closed </placeName> tag, as in the following example:

<place xml:id="birch_bay">
   <placeName>Birch Bay</placeName>
   <location>
      <geo>48.895159,-122.789767 48.894745,-122.784574</geo>
   </location>
   <desc>Birch Bay is located […]</desc>
</place>

The location appears inside a <geo> tag, and consists of one or more coordinates in lat,long format. Each lat,long pair is delimited by a comma (with no space), and each pair is delimited by a space.

How to acquire coordinates

We recommend using Greg Newton’s Mercator Vertexer tool to generate your coordinates. Choose the type of location you need to specify (line or polygon), draw the shape, then copy/paste the coordinates into the <geo> tag.

Polygons

Use a polygon, or multiple coordinates, when you wish to draw a bounding box around a given location, as in the following:

- A political region, such as province or territory
- Cities
- Bays and harbours
- Islands
- Groupings of islands, as in the Gulf Islands

Here is an XML example of what a polygon looks like. It’s just multiple coordinate-pairs, separated by spaces, which by default become polygons:

<location>
   <geo>48.408722,-123.303165 48.40992,-123.307962 48.412258,-123.310184 48.412148,-123.314028 48.410755,-123.314653 48.410502,-123.316737 48.409498,-123.314704 48.40801,-123.314516 48.404392,-123.321147 48.405268,-123.324382 48.407399,-123.326417 48.410007,-123.324949 48.411148,-123.327772 48.410808,-123.329652 48.409657,-123.328475 48.408022,-123.328672 48.406781,-123.331005 48.407489,-123.335755 48.409589,-123.340193 48.40604,-123.347867 48.40259,-123.347078 48.401785,-123.349192 48.402511,-123.350844 48.40529,-123.352553 48.406445,-123.357223 48.406646,-123.362614 48.405282,-123.364127 48.405574,-123.366381 48.407867,-123.373635 48.408181,-123.377414 48.409548,-123.379823 48.412454,-123.381207 48.413308,-123.385434 48.411941,-123.391743 48.413664,-123.394489 48.417399,-123.39239 48.417616,-123.389561 48.418904,-123.388281 48.419886,-123.390184 48.421166,-123.389484 48.422188,-123.389415 48.424431,-123.388846 48.42444,-123.385896 48.423865,-123.379362 48.424709,-123.378568 48.425029,-123.376379 48.4251,-123.373203 48.428176,-123.371851 48.431137,-123.372173 48.433358,-123.377237 48.435465,-123.378868 48.440476,-123.38213 48.457327,-123.376637 48.452318,-123.32119 48.452631,-123.290892 48.447024,-123.288746 48.437316,-123.289776 48.436106,-123.293982 48.436401,-123.296792 48.437664,-123.298573 48.432749,-123.303187 48.430695,-123.302066 48.428868,-123.30412 48.428294,-123.305617 48.425558,-123.305936 48.42718,-123.301467 48.425699,-123.299315 48.420344,-123.296133 48.414292,-123.294714 48.413626,-123.292364 48.411906,-123.292159 48.409976,-123.295569 48.410289,-123.298337</geo>
</location>

Below is an example of what a polygon looks like in the “Places” index. Note that it’s also acceptable to repeat the final coordinate in order to clarify that this is a closed shape rather than a path.

Lines

Use lines for rivers, streams, and portages, or anything else that runs only point-to-point and beware, you’ll end up with an odd-looking blob in Google Maps if you don’t read this section carefully!

To make a line you need to override the code that automatically converts multiple geo coordinates to polygons.

To perform the override, you need to add a @type="path" attribute to the <location> tag, as in the following example:

<location type="path">
   <geo>49.841433,-121.437864 49.841290,-121.431828 49.840316,-121.429032 49.840574,-121.427302 49.842634,-121.424727 49.842748,-121.420245 49.832190,-121.392565 49.823849,-121.381957 49.811043,-121.377359 49.797728,-121.377838 49.782741,-121.379241 49.768209,-121.381333 49.755055,-121.378814 49.745973,-121.375444 49.739060,-121.374764 49.737644,-121.371080 49.708852,-121.354923 49.692304,-121.348739 49.685304,-121.345646 49.681848,-121.338788 49.681646,-121.334049 49.673524,-121.315724 49.671545,-121.312780 49.666503,-121.309940 49.664242,-121.310521 49.651262,-121.306125 49.643646,-121.301944 49.632702,-121.294378 49.626014,-121.283190 49.620264,-121.262946 49.617220,-121.239976 49.613393,-121.221962 49.614152,-121.211861 49.614448,-121.202692 49.613209,-121.196872 49.613670,-121.191770 49.616433,-121.177789</geo>
</location>

Below is an example of what a line looks like in the “Places” index:

How to map a location with the Mercator Vertexer tool

- Make sure the place isn’t mapped yet. In the example below, taken from the place.xml file, we can see that there are no geo coordinates within the <geo> tags, so the place isn’t mapped yet.
- Determine what type of location you’re working with (e.g. city, province, river) and decide accordingly whether to map it as a point, polygon, or line. Since Bristol is a city in England, we’ll map it as a point.
- Assuming you’re working on a computer with two monitors, locate Bristol in Google Maps on one monitor.
- Open the Mercator Vertexer tool on the other monitor and locate Bristol. As of February 2019, the tool does not allow searches, even though there’s a search bar in the upper-left corner, so we need to find Bristol manually. The Google Maps page on your first monitor will help you locate Bristol on Vertexer. Tip: if you’re not familiar with Vertexer, click on the big question mark at the bottom-right corner. A Help/Tutorial window will pop up that will walk you through the mapping process.
- In the upper-right corner of Vertexer, there’s a drawing panel with four tools: hand cursor (allows you to move around the map), simple marker (for adding points), polygon (for drawing polygons), and polyline (for drawing lines). Since we’ll map Bristol as a point, we’ll use simple marker. To place Bristol on Vertexer, click on the simple marker tool and then click on Bristol. A green marker will appear above the point clicked, and there will be a single pair of lat,long coordinates in the selected feature box.
- Now you can add the coordinates to the entry in the place.xml file, which will create a map link. Click on the coordinates in the “Selected Feature” box and copy/paste them into the entry in the place.xml file within the <geo> tags. Remember to save your work. Note: when you add the coordinates of a line to place.xml, remember to add the attribute @type="path" to the <location> tag.

- When drawing polygons, perfect precision is appreciated but not required. Consult your Despatches colleagues if you have any questions
- Remember mapping can be controversial. Some places included in the placeographies have been entangled in historical and current territorial disputes. As of February 2019, the project prefers mapping places in accordance with their current locations and boundaries.
- Places identified as First Nation locations in Canada require particular caution. In these cases, if we can find current “official” maps created by the appropriate group, it’s a good idea to use their maps. If you use a cartographic resource other than Google Maps, please indicate the source as a comment in the place.xml file.

Rules for unique placeography IDs/values

This section assumes that you already know how to add “placeholder,” or content-free, entries to the places.xml file. If not, then consult your Despatches colleagues before you proceed.

This section discusses cases where a new-found place name consists of two or more words. For example, “Beacon Hill”.

Here’s what we’ve done so far:

- If a place name consists of two or more words, make sure you do not leave a space between words in the @key value. <name type="place" key="beacon_hill">Beacon Hill</name>
- Always use the full name of the place in the value so that it’ll sort correctly on the website, though you can also combine two names with an underscore. <name type="place" key="beaver_lake_settlement">Beaver Lake Settlement</name>

How to indicate incomplete place entries

When a place entry is empty or incomplete we need to track it for statistics purposes, and for easy searching. To mark a place entry as incomplete, please add the attribute @type="unavailable", "incomplete", or "rudimentary" to the <placeName> tag, as in the following examples:

<place xml:id="seleassa">
   <placeName type="unavailable">Archer</placeName>
   <location>[...]</location>
   <desc>Content not yet available.</desc>

</place>

Note that we add the statement “content not yet available” to the content. Or, in cases where we have added a little bit of content, we handle it as in the following example:

<place xml:id="statapoosten">
   <placeName type="incomplete">Statapoosten</placeName>
   <location>[...]</location>
   <desc>In <date when="1859">1859</date>, the Northwest Boundary Survey established Statapoosten, or Statapoostin, as an astronomical station slighty east of Gilpin. The map provided, above, covers two high points in the area that they might have used.</desc>

</place>

Note that this place has no references, so it is clear that the research is not complete. If some research has been done, and a basic entry has been written, but you believe that more research would yield a more useful description, you can mark the entry as "rudimentary":

<place xml:id="port_staniforth">
   <placeName type="rudimentary">Port Staniforth</placeName>
   <location>[...]</location>
   <desc>At present, there is no known location for a Port Staniforth. However, there is a a Staniforth Point in the area <name key="pike">Pike</name> refers to as Port Staniforth.</desc>
   <desc>
      <listBibl>
         <bibl xml:id="port_staniforth_b_1">1. <title level="a">
               <ref type="external" target="http://www4.rncan.gc.ca/search-place-names/unique/JCOPT">Staniforth Point</ref>,</title>
            <title level="m">Natural Resources Canada</title>.</bibl>
      </listBibl>
   </desc>

</place>

Note that if you are linking to another Despatches document using the cdc: prefix, you can add @type="citation" to the <ref> tag, and then the content of the <ref> element will be replaced by the full citation of the document during the build process. This is a convenient way to provide a detailed and accurate citation without much trouble.

Vessels

Writing vessel entries

These instructions assume that you’ve already read several vessel entries, and that you have at least a passing interest in the subject!

As with biographies and “placeographies,” website readers can click on a vessel name to learn about it. Vessels appear as mentioned in the letters, but readers can view all the vessels as a collection on the vessels index page.

The following is a working list of things to consider for your vessel entries:

- Keep it brief--aim for roughly 200 words.
- When possible, include date of launch and fate, that is date of decommission, when it was dismantled, or sunk!
- Pull in interesting content from the despatches, should the ship be mentioned in the collection.
- Mention who owned the boat.
- Add any fun or significant facts you can find. If you’re not sure about whether or not to include something, consult your Despatches colleagues.

See Research Resources section for a list of books and websites you can consult for source material.

Usage tips, with examples

The world of ships and vessels has all kinds of weights, measures, and technical details to consider. See the CMOS 8.116 for more information. Here’s a working list of usage tips:

- We write in metres and tonnes, not yards and tons. See the Preferred Spelling section for more information.
- Even if your source material is presented in feet convert it to metres. And always round your numbers. For example, a 235-foot ship is 71.628 metres in length, which we would round up, in this case, to 72 metres.
- As a general rule, ignore the tonnage of ships; it’s an editor/writer’s nightmare. It can be difficult, especially when one deals with old sources, to determine whether or not “tons” refers to Builder’s Old Measurement [BOM or bm] or some other form of “tonnage,” which measure capacity, not weight, and this is not to be confused with displacement tonnage. But, if you have to include it for the sake of disambiguation, then consider the following. Even if your source material is presented in tons, convert it to (metric) tonnes. Where ship weights are concerned, especially for British vessels, these would be in long tonnes. This is all quite confusing to young minds, who grew up as metric-only natives. Here’s a cheat sheet:

- Tonne = 1000kg, nothing to do with old-timey weights. This is the tonne we use in Canadian weights and writing.
- British tonne, spelled the same way to confuse you, = 2,240 pounds. Almost certainly this is the weight used for any 19th-century ships.
- US ton = 2000 pounds. It’s the United States that refer to “metric tons,” or 1000kg, when they want to distinguish it from their tons.
- So, most Canadian-published books we use, such as Scott’s The Encyclopedia of Raincoast Place Names, already write in metres and tonnes. But, be on alert for US-published books that write “tons” in reference to ships, when they mean (long) tonnes! Arg.

- We abbreviate “metres” to “m.” E.g. this steam-powered ship was 48 m long and 11 m wide. Note the space between the numbers and the “m.”
- As CMOS notes “when such abbreviations as USS (United States ship) or HMS (Her [or His] Majesty’s ship) precede a name, the word ship or other vessel type should not be used.”

- Wrong: HMS ship Alarm.
- Correct: HMS Alarm.

- All ship names must be capitalized and italicized.
- Do not italicize “HMS,” “USS,” or anything similar.

- Wrong: HMS Alarm.
- Correct: HMS Alarm.

Here’s an example of what a completed vessel entry looks like, as taken from the “indexes” page:

Tagging vessel entries

How to tag vessels that appear in the correspondence files

This one is pretty straightforward: wrap the correct tag around it. <name type="vessel" key="topaze">Topaze</name>

If you need the unique ID of a given vessel, the “key=” value, refer to the vessels index page. Hover your mouse over a given vessel’s name and its key value will appear. The same is true for people and places.

NOTE: In cases where you encounter HMS before a ship name, as in HMS Discovery, tag only “Discovery.” HMS is not part of the vessel name; furthermore, if you tag the HMS it will be rendered in italics along with the ship name, which is counter to Chicago style (see CMOS 8.116).

How to add a new vessel to the database

This process is, more or less, the same for adding newly discovered people to the database. See the Adding new names to the database section for details.

Note that unlike the biographies, which have separate files for each year, the vessels are in two files: vessels.xml (which you will use almost exclusively) and the peripheral_vessels.xml file (which you will use rarely). The latter file is for famous vessels that don’t happen to appear in the collection, or vessels that we mention in our bios or placeographies. Talk to your Despatches colleagues if you are unsure which file to use!

Placeholder template for new vessels

Note that this is a placeholder only, one to which we have yet to add content. The short-cut key for this placeholder is Ctrl Alt 2.

<item xml:id="${caret}">
   <label>
      <name type="vessel" key="KEY">VESSEL NAME</name>
   </label>
   <p/>
</item>

NOTE: As ever, if you're unsure as to what a complete vessel entry looks like, go to the vessels file ([…]/xml/vessels/vessels.xml) and look at a completed entry!

How to tag vessel entries in the vessels.xml file

Let’s look at an example of a completed vessel entry from the vessels.xml file. This example has all the typical components of a completed entry including all the usual markup, ref links to despatches, and a complete set of footnotes with corresponding superscript indicators.

<item xml:id="bacchante">
   <label>HMS <name type="vessel" key="bacchante">Bacchante</name>, <date from="1859" to="1879">1859-1879</date>
   </label>
   <p>The HMS <name type="vessel" key="bacchante">Bacchante</name> was a screw-driven steam frigate with 51 guns and a complement of 560 sailors.<bibl>
         <hi style="vertical-align: super; font-size: 80%;">1</hi>
      </bibl>
   </p>
   <p>This large ship, at 72 m, frequented <name type="place" key="esquimalt">Esquimalt</name> in the <date from="1860" to="1869">1860</date>s under the command of Captain Donald Mackenzie and it served as flagship to <name key="maitland">Maitland</name>, commander-in-chief of the Pacific squadron from <date from="1860" to="1862">1860-62</date>.<bibl>
         <hi style="vertical-align: super; font-size: 80%;">2</hi>
      </bibl>
   </p>
   <p>The <name type="vessel" key="bacchante">Bacchante</name> was launched at <name type="place" key="portsmouth">Portsmouth</name> in <date when="1859">1859</date> and commissioned for service on the Pacific station on <date when="1860-04-18">18 April 1860</date>.<bibl>
         <hi style="vertical-align: super; font-size: 80%;">3</hi>
      </bibl> Its design, along with several other vessels, including the <name type="vessel" key="topaze">Topaze</name>, was based on the lines of the <name type="vessel">Shannon</name>
       (1855).<bibl>
         <hi style="vertical-align: super; font-size: 80%;">4</hi>
      </bibl>
   </p>
   <p>
      <ref target="cdc:V627092">This correspondence</ref> from <name key="newcastle">Newcastle</name> to <name key="douglas_j">Douglas</name> notes the absence of guns at <name type="place" key="victoria">Victoria</name> and <name type="place" key="esquimalt">Esquimalt</name> and reports that <q>arrangements have been made for landing two 68 [pounder] Guns which may be spared from H.M.S. <q>
            <name type="vessel" key="bacchante">Bacchante</name>
         </q> and <q>
            <name type="vessel" key="topaze">Topaze</name>
         </q>.</q>
   </p>
   <p>
      <listBibl>
         <bibl>1. Andrew Scott, <title level="m">The Encyclopedia of Raincoast Place Names</title> (Madeira Park, BC: Harbour Publishing, 2009), 54.</bibl>
         <bibl>2. Ibid.</bibl>
         <bibl>3. <title level="a">
               <ref type="external" target="http://www.pbenyon.plus.com/18-1900/B/00435.html">Bacchante</ref>,</title>
            <title level="m">Index of 19th Century Naval Vessels</title>.</bibl>
         <bibl>4. William Laird Clowes, <title level="m">The Royal Navy: A History</title> (London: Sampson Low, Marston and Company, 1901), 6:199.</bibl>
      </listBibl>
   </p>

</item>

Rules for unique vessel IDs/values

This section assumes that you already know how to add “placeholder,” or content-free, entries to the vessels.xml file. If not, then consult your Despatches colleagues before you proceed.

This section discusses cases where a new-found vessel’s name consists of two or more words. For example, the Mary Dare.

Here’s what we’ve done, so far:

- If a vessel name consists of two or more words, make sure you do not leave a space between words in the @key value. <name type="vessel" key="mary_dare">Mary Dare</name>
- Always use the full name of the vessel in the value so that it will sort correctly on the website, though you can also combine two names with an underscore. <name type="vessel" key="prince_of_the_seas">Prince of the Seas</name>

Vessels not in the Despatches

In some cases, you may mention a vessel that doesn’t appear in the despatches. For example, in a biography pop-up about Captain Cook, we may mention HMS Discovery.

First, be certain that the ship isn’t mentioned in the despatch collection. To do this, use the search feature in Oxygen where you can search all files and folders.

Once you’ve established the given vessel's absence from the despatch collection and related files—that is, places.xml, vessels.xml, peripheral_vessels.xml, and all the biography files—add your new vessel to the “peripheral_vessels.xml” file.

See the section above, Rules for unique Vessel IDs/values, for information on creating unique identifiers for vessels, otherwise, please consult your Despatches colleagues on the process required to create a new vessel tag and entry in the “peripheral_vessels.xml” file.

How to indicate incomplete vessel entries

When a vessel entry is incomplete we need to track it for statistics purposes, and for easy searching. To mark a vessel entry as incomplete, please add the attribute @subtype="incomplete" to the <name> tag, as in the following example:

<item xml:id="archer">
   <label>
      <name subtype="incomplete" type="vessel" key="archer">Archer</name>
   </label>
   <p>Content not yet available.</p>

</item>

Note that we add the statement “content not yet available” to the content. Or, in cases where we have added a little bit of content, we handle as in the example below: <p>According to <ref target="cdc:V605LN06">this document</ref>, this ship was an HBC party barge. Further content not yet available.</p>

Organizations

This section describes the addition of organization entries to the orgography and tagging entities. Organizations are entities like government departments, religious groups and private corporations.

Adding an organization to the index

The orgography is located at orgs/organizations.xml. It is organized by type and then alphabetically. The current org types are:

- Miscellaneous
- Governmental Institution
- Religious Affiliation
- Private Corporation
- Legal Organization

A standard organization entry looks like this:

<org xml:id="emigration_office" type="governmental">
   <orgName>Emigration Office</orgName>
   <desc>The Colonial Land and Emigration Commission was established in <date when="1840">1840</date>. A board of commissioners was appointed to manage the sales of Crown lands in British colonies and regulate emigration from the UK to the colonies. The commissioners had the power to use the proceeds from land sales to defray the expense of emigration. They corresponded with colonial governors indirectly through the Colonial Secretary (head of the Colonial Office). They also supervised the emigration officers stationed in British colonies. The first board rented a private house for their office space on Park Street, Westminster, <name type="place" key="london">London</name>.<bibl corresp="#eo_b_1">
         <hi style="vertical-align: super; font-size: 80%;">1</hi>
      </bibl>
   </desc>
   <desc>It became Emigration Commission in <date when="1856">1856</date> after the imperial government had granted the rights of administering Crown lands to the colonial governments.<bibl corresp="#eo_b_2">
         <hi style="vertical-align: super; font-size: 80%;">2</hi>
      </bibl> In <date when="1878">1878</date>, the Commission was replaced with Emigration Department set up in the <orgName key="co">Colonial Office</orgName>.<bibl corresp="#eo_b_3">
         <hi style="vertical-align: super; font-size: 80%;">3</hi>
      </bibl>
   </desc>
   <desc>
      <listBibl>
         <bibl xml:id="eo_b_1">1. Fred H. Hitchins, <title level="m">The Colonial Land and Emigration Commission</title>, (Pennsylvania: University of Pennsylvania Press, 1931), 42-45, 59, 159.</bibl>
         <bibl xml:id="eo_b_2">2. Ibid., 310.</bibl>
         <bibl xml:id="eo_b_3">3. Ibid., 94.</bibl>
      </listBibl>
   </desc>
</org>

This example can be used as a template. Make sure to change the @type on the <org> if necessary. Also tag other entities as required.

Tagging orgs

All organizations in our orgography should be tagged throughout the database. In the despatches and the abstracts, organizations are tagged with an <orgName> and unique id in a @key.

<orgName key="hbc">Hudson's Bay Company</orgName>

That's it! After all the people, place and vessel tagging this is no great challenge, just remember that it is <orgName> and not <name> and you're good to go.

Miscellaneous notes

Document taxonomy

Eventually there will be document categories <catRef> elements to classify documents into types. [In progress 2019-02-14 LM]

Regular expressions for Oxygen

These are used in on Oxygen’s find/replace dialogue and can apply to individual files when you Ctrl+F in one document, or on multiple files, when you select folders and right-click > Find/Replace in files.

Lookahead and lookbehind

Use this search type to find phrases excluding certain words. For example, if you want to find Hudson's Bay, but without “Company,” “House,” “Territory,” and so on:

Hudson's Bay (?![Cc]o)(?![Hh]ouse)(?![Tt]er)

Here’s another simpler way to achieve similar results:

Hudson's Bay [^CHch]

The above asks the search to catch “Hudson's Bay” but without words that contain “C” as in “Company” or “H” as in “House,” and the lower case of each. In this search, I wanted to find instances of “Hudson's Bay Territory” or “Hudson's Bay Territories,” and this trimmed the results to a manageable level.

Location independence

Use this template to find two instances on separate lines in the same file or document, as long as the first term appears before the second in a given file:

(?=.*search term).*second search term

For example, let's say we wanted to find all the files that contained the word “Douglas” AND the word “coal”:

(?=.*Douglas).*coal

The example above was taken from this site.

More regular expression examples

- The example below finds instances of “1861” excluding “1861” with a dash, quotation mark or “</” immediately after it (e.g. 1861</). 1861(?!</)(?!-)(?!")
- The example below is used to find instances where any number (the “\d” part, “d” = “digit”) is followed by (the “+” part) the letter “m.” I was looking for things such as 37m, 33m, 55m, and so on. \d+m
- The example below is to find the word “Instant” when it’s the first word on a line. ^Instant
- The example below is used to find a name element followed by a new line that starts with “TFE” (initials). <name>(\n)^TFE
- The example below moves all instances of “HMS” outside of quotes. Note that “( )” gets rid of spaces after “HMS” to satisfy the schematron after it’s been replaced.

Find: (<name type="vessel" key="[a-z]+?">)(HMS)

Replace:
$2 $1

- The example below finds all initials marked up with square brackets inside tags and moves the brackets out of tags.

Find: (<name>)(\[)(.+)(\])(</name>)

Replace:
$2$1$3$5$4

- The example below finds all elements that contain only two words. >[A-Z][a-z]+\s[A-Z][a-z]+<
- The example below finds all the dates that are written in the format “25 December 2018.” \d{1,2}\s[A-Z][a-z]+\s\d{4,4}

Xpath examples

Use the following examples in the “Xpath in Files…” function in Oxygen to answer each query.

- How many <name> elements are there in this doc?

- //name

- How many of these are vessels?

- //name[@type='vessel']

- How many of these vessels are located in a <p> element?

- //p/name[@type='vessel']

- Find all instances where Douglas sent a confidential letter to London in C0/60:

- //idno[contains(@type,'documentType')][contains(.,'Confidential') or contains(.,'Private')][ancestor::teiHeader/descendant::author[name='Douglas']][ancestor::teiHeader/descendant::idno[@type='coNumber'][.='60']]

Keyboard shortcuts: Mac

This list should suffice.

Keyboard shortcuts: Windows

This list should suffice.

Permissions script

[Martin will fill this section in as of 2019-02-14 LM]

Snippets

Snippets of particularly interesting passages in the despatches are displayed at random on the Despatches home page. You can click on the snippet and it will link you to the file. However, it’s our job to find the passages. So, should you come across the a juicy tidbit that you think worthy of notice, please ask tag it like this: <p>[…]<seg type="snippet" xml:id="V58002_snippet_1">this is a shocking or interesting fragment of text</seg>[…]</p> Create a unique @xml:id attribute for the snippet by concatenating the ancestor TEI element's @xml:id (without the trailing .scx if there is one) with “_snippet_” and the number of that snippet in the document.

Research resources

There are hundreds of sources that have been used in the Despatches writing. The following resources are only meant as a starting point.

Should you find the author or publication suspect, please consult the Despatches team.

Websites

- The Oxford DNB
- The Dictionary of Canadian Biographies
- Hudson's Bay Company Archives' Biographical sheets
- The Canadian Encyclopedia (generally, more for context on well-known figures)
- The American National Biography
- The British Colonist Archives
- Andrew Scott’s The Encyclopedia of Raincoast Place Names online
- Encyclopaedia Britannica online
- William Loney RN for Royal Navy information

Books

- Alexander Begg’s History of British Columbia
- Some Reminiscences of Old Victoria , Edgar Fawcett (UVic libraries link, full-text e-book)
- Captain John T. Walbran’s British Columbia Coast Names. We keep a copy in the office, and it’s available in the library, call number: FC3806 W35 1971a.
- Great subject guides for Victoria and Vancouver Island the UVic Libraries.

Documentation sandbox

NOTE: THIS SECTION DOES NOT CONTAIN ACTUAL DOCUMENTATION.

Use this section for test-encoding anything that you want to experiment with in the documentation. We will eventually delete it.

<div>
   <head>This is a heading.</head>
   <p xml:lang="en">This is a paragraph.</p>

</div>

This paragraph mentions the <pb> element, the @facs attribute, and the value "stuff.jpg". It also uses the <tag> element: <pb facs="stuff">. Because the <pb> element is in our Despatches schema, it is linked automatically to its specification, but because the <tag> element is not in our schema, it isn't linked.

This paragraph talks about entity references, such as &amp; for the ampersand (&), and &#x2014; for the em dash (—). You can see from these examples how to encode an entity so that it shows the actual character, or it shows the entity reference. If you wrap the latter in a <code> element, it will look better: &amp;.

This does not seem to be a valid CSS property name. Sydney, "strikethrough" is not a valid CSS value. The correct form is text-decoration: line-through. Sydney, this is not correct CSS. You probably need either: font-weight: bold; or font-style: italic; Do not include spaces at the beginning or end of name or title elements. Do not include the possessive suffix inside a name tag. Do not include the possessive suffix inside a name tag. Do not include trailing punctuation inside a name or ref tag. "Ibid" must be followed by a period. "Ibid" should begin with a capital letter and be followed by a period. Bibl entries must begin with a number, followed by a period and a space. Superscripted footnote numbers must appear after punctuation, not before. The convention for bibl xml:id = "xml:id here_b_number of endnote here". bibl @corresp must match corresponding bibl @xml:id in footnotes. bibl indicator must be an integer with no preceding or trailing spaces. number of @xml:id must match the number of the citation. bibl indicator must immediately follow a period or a closing q tag. title elements should not be immediately followed by alphanumeric characters. You need a space or a punctuation mark followed by a space. Snippets may not contain elements which turn into blocks in the HTML output. Keep your snippets as simple and short as possible, and avoid content which has page-breaks, marginalia or other problematic blocks. No double quotes inside a q tag. No double quotes inside a q tag. No double quotes. Please use <q> and <soCalled> instead. No double quotes. Please use <q> and <soCalled> instead. No double quotes. Please use <q> and <soCalled> instead. No double quotes. Please use <q> and <soCalled> instead. No double quotes. Please use <q> and <soCalled> instead. No double quotes. Please use <q> and <soCalled> instead. No double quotes. Please use <q> and <soCalled> instead. No double quotes. Please use <q> and <soCalled> instead. @rend should not be used for CSS code. Please use the @style attribute for CSS. Only lower-case letters without spaces should be used in @xml:id attributes for people, places and vessels. This image link seems to be incorrect. div with @type='enclosures_transcribed' must have at least one div with @type='enclosure_transcribed'. Vessel prefixes, "HMS", "RMS", "USS", must come before the name tag. ERROR: No spaces are allowed at the beginning or end of a q element.

<revisionDesc>
@status
Shows the status of the document.
The @status attribute is used to track the current status of the document with regard to proofing.
"unproofed"
Not yet proofed.
"proofed"
Proofed and clear for publication..

<p>
@n
@xml:lang
@rendition
@corresp
@facs

<emph>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<hi>
Do not nest hi elements; put multiple CSS rules in the same hi element's style attribute.
@n
@xml:lang
@rendition
@corresp
@facs

<quote>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@type
@subtype

<cit>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@type
@subtype

<desc>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<term>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@target
@type
@subtype
@key
@cRef

<sic>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@resp

<corr>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@type
@subtype

<choice>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<reg>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@resp
@type
@subtype

<orig>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@resp

<add>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@resp
@place
"above"
"below"
@type
@subtype

<del>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@type
@subtype

<unclear>
@hand
@agent
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<name>
The @key attribute must have a value consisting of lower-case letters and underscores, and cannot be empty. The @key attribute must point to a person, place or vessel. Do not nest one name element inside another. If you make a name @type='ip' (Indigenous People/Person) then you must supply @subtype="group" or @subtype="individual".
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@resp
@type
"addressee"
The person to whom a letter is addressed.
"ip"
This name refers to an Indigenous person or group. Should always be paired with @subtype.
"place"
This name refers to a place in the placeography.
"vessel"
This name refers to a vessel in the vesselography.
"incomplete"
(Only used in -ography files) Some content exists for this item, but it is unfinished or inadequate, and will be rewritten in future.
"unavailable"
(Only used in -ography files) No content has been written for this item yet.
"sent"
Indicates the sent date of a document.
"received"
Indicates the sent date of a document.
@subtype
"incomplete"
Some content exists for this item, but it is unfinished or inadequate, and will be rewritten in future.
"group"
This name or appellation refers to a group.
"individual"
This name or appellation refers to an individual person.
"unavailable"
No content has been written for this item yet.

<address>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<addrLine>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<date>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@resp
@subtype

<abbr>
@type
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@resp
@type
@subtype

<sense>

<expan>
@n
@rend
@rendition
@corresp
@facs

<ptr>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@type
@subtype
@cRef

<ref>
ERROR: target attributes must not contain spaces. ERROR: target attributes must never have a hard-coded link to bcgenesis.uvic.ca. Use a cdc: link. ERROR: target attributes using the cdc: link scheme do not need ".scx" at the end. ERROR: Do not include leading or trailing spaces in ref elements.
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@cRef
@type
"CONTENTdm"
"appURI"
"citation"
A link whose contents should be turned into a full citation of the target document.
"co_ref"
"confirm_receipt"
"doc"
"document"
"external"
"map"
"marginalia"
"provisional"
@subtype

<list>
@type
"simple"
"ordered"
"vessels"
@n
@xml:lang
@corresp
@facs

<item>
@xml:lang
@rend
@rendition
@corresp
@facs

<label>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@subtype
@place

<head>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@type
@subtype

<note>
@anchored
@targetEnd
@xml:lang
@rend
@rendition
@corresp
@facs
@place
@target
@resp
@type
@subtype

<index>
@indexName
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<graphic>
@xml:lang
@rend
@rendition
@corresp
@facs

<milestone>
@n
@xml:lang
@rendition
@corresp
@facs
@unit
"section"
@type
@subtype

<pb>
Don't use @n for links to page-images. Use @facs instead. Page breaks cannot appear as children of table elements or row elements. Put them inside cells. Spaces are not allowed in @facs.
@xml:lang
@rend
@rendition
@corresp
@type
@subtype

<pb facs="co_60_22/co_60_22_00055r.jpg"/>

The Despatches project uses the @facs attribute to specify a link to the page-image for the page following the break.

<lb>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@type
@subtype

<series>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<author>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@key

<respStmt>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<resp>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@key

<title>
@level
"a"
"j"
"m"
"s"
"u"
@type
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@key
@type
@subtype

<publisher>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<biblScope>
@type
"startPageImage"
"subject"
@from
@to
@n
@xml:lang
@rend
@rendition
@corresp

<bibl>
@type
The type of bibliography item in a bibliography.
"book"
A book or monograph
"journal_article"
A journal article
"map"
A map
@n
@rend
@rendition
@facs
@subtype

<listBibl>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@type
@subtype

<particDesc>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<table>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<row>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<cell>
@n
@xml:lang
@rendition
@corresp
@facs

<teiHeader>
@type
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<fileDesc>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<titleStmt>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<funder>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<publicationStmt>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<idno>
Replace "???" with a page number, this element cannot be empty either.
@type
"CONTENTdm"
A reference number in the university's CONTENTdm system.
"coNumber"
"coRegistration"
"coVol"
"despatchNo"
The sequential number of a despatch within a series.
"despatchType"
A classifier such as "Judicial", "Financial", or "Miscellaneous".
"documentCategory"
Despatch to London, Despatch from London, Correspondence (private letter), Public Offices document, or Other.
"doc_id"
Unique document identifier.
"archivalId"
Concatenation of archive, series and volume which is generated during build process for convenience.
"documentType"
"libFileName"
"nacRecordGroup"
"nacCollection"
"page"
"penfoldNum"
"received"
"repoNumber"
"repoVol"
"repository"
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<notesStmt>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<sourceDesc>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<encodingDesc>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<tagsDecl>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<rendition>
@scheme
@scope
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<appInfo>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<application>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@type
@subtype
@when

<profileDesc>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<catRef>
@target
"cdt:cdtOriginal"
The original document sent by the writer and received by the addressee.
"cdt:cdtDraft"
The draft of a document (usually, but not always, subsequently transcribed, signed and sent).
"cdt:cdtLetterbook"
The letterbook copy of a document kept by the author/sender.
"cdt:cdtCopy"
A (non-letterbook) copy of the document.
"cdt:cdtSchedule"
A schedule compiled by Colonial Office staff.
"cdt:cdtSentToLondon"
Documents sent to offices in London, such as the Colonial Office.
"cdt:cdtSentFromLondon"
Documents sent from offices in London, such as the Colonial Office.
"cdt:cdtSentToColony"
Documents sent to one of the colonies, normally to the colonial governor.
"cdt:cdtSentFromColony"
Documents sent from one of the colonies, normally by the colonial governor.
"cdt:cdtNumbered"
The document has a number of some kind, such as a Colonial Office registration number. Many documents will have multiple numbers.
"cdt:cdtSeriesNumber"
The document has a series number, such as the numbering applied to despatches to and from London.
"cdt:cdtCoNumber"
The document has a Colonial Office registration number (assigned on receipt in London).
"cdt:cdtBoardOfTrade"
The Board of Trade
"cdt:cdtColonialOffice"
The Colonial Office
"cdt:cdtForeignOffice"
The Foreign Office
"cdt:cdtLandBoard"
The Land Board
"cdt:cdtWarOffice"
The War Office
"cdt:cdtFinancial"
A document that discusses financial or economic issues.
"cdt:cdtLegal"
A document that discusses judicial or legislative issues.
"cdt:cdtEconomicActivity"
A document that discusses economic activity in the colonies.
"cdt:cdtFarming"
A document that discusses farming.
"cdt:cdtResources"
A document that discusses resources other than mining, coal, gold, and lumber.
"cdt:cdtMining"
A document that discusses mining.
"cdt:cdtCoal"
A document that discusses coal.
"cdt:cdtGold"
A document that discusses gold.
"cdt:cdtLumber"
A document that discusses lumber.
"cdt:cdtFishing"
A document that discusses fishing and fisheries.
"cdt:cdtHunting"
A document that hunting.
"cdt:cdtTaxation"
A document that discusses taxes and licences.
"cdt:cdtTrade"
A document that discusses trade.
"cdt:cdtImport"
A document that discusses trade imports.
"cdt:cdtExport"
A document that discusses trade exports.
"cdt:cdtInternalTrade"
A document that discusses internal trade (between colonies, between Indigenous groups and peoples, or any combination of the two).
"cdt:cdtSecurity"
A document that discusses colonial security and issues related to the same.
"cdt:cdtPolicing"
A document that discusses policing.
"cdt:cdtArms"
A document that discusses arms, weapons, and ordnance.
"cdt:cdtMilitary"
A document that discusses military security, deployment, or protection.
"cdt:cdtNavy"
A document that discusses the navy.
"cdt:cdtArmy"
A document that discusses the army.
"cdt:cdtInfrastructure"
A document that discusses the creation of infrastructure, such as buildings, roads, bridges, etc., in the colonies.
"cdt:cdtBuildings"
A document that discusses the construction and maintenance of buildings.
"cdt:cdtBridges"
A document that discusses poltical relations with the United States.
"cdt:cdtRoads"
A document that discusses poltical relations with Spain.
"cdt:cdtPublicWorks"
A document that discusses poltical relations with Indigenous groups and peoples.
"cdt:cdtMarine"
A document that discusses poltical relations with Great Britain.
"cdt:cdtRail"
A document that discusses poltical relations with the Hudson's Bay Company.
"cdt:cdtCommunications"
A document that discusses poltical relations with the Hudson's Bay Company.
"cdt:cdtTelegraph"
"cdt:cdtMail"
"cdt:cdtInternationalRelations"
A document that discusses relations between one or both colonies and other geopolitical entities, groups, organizations, and peoples.
"cdt:cdtRussia"
A document that discusses poltical relations with Russia.
"cdt:cdtUnitedStates"
A document that discusses poltical relations with the United States.
"cdt:cdtSpain"
A document that discusses poltical relations with Spain.
"cdt:cdtIndigenous"
A document that discusses poltical relations with Indigenous groups and peoples.
"cdt:cdtGreatBritain"
A document that discusses poltical relations with Great Britain.
"cdt:cdtHudonsBayCompany"
A document that discusses poltical relations with the Hudson's Bay Company.
"cdt:cdtPersonal"
A personal letter (often a solicitation for an appointment or posting).
"cdt:cdtPrivate"
A private document, normally marked as such in the header.
"cdt:cdtSeparate"
A separate document, normally marked as such in the header.
"cdt:cdtAccounting"
The document contains financial information in some structured format, such as a table of expenditures.
"cdt:cdtMinutes"
The document contains or consists of minutes (usually written by Colonial Office staff).
"cdt:cdtMarginalia"
The document contains marginal annotations of some kind.
"cdt:cdtMap"
The document is a map, or has a map drawn on one of its pages.
"cdt:cdtEnclosures"
The document contains enclosures or attachments. Subcategories for different types of enclosures and attachments are provided for further specificity.
"cdt:cdtEnclosedTranscribed"
The document contains at least one attachment or enclosure that has been transcribed.
"cdt:cdtEnclosedUntranscribed"
The document contains at least one attachment or enclosure that has not yet been transcribed.
"cdt:cdtEnclosedMissing"
The document originally contained one or more attachments or enclosures, which are not in the file.
"cdt:cdtEnclosedMap"
The document contains at least one map as an attachment or enclosure.
"cdt:cdtEnclosedDraft"
The document contains at least one attachment or enclosure that is a draft of another document.
"cdt:cdtEnclosedAct"
The document contains at least one attachment or enclosure that is an act of parliament. These are usually printed.
"cdt:cdtEnclosedLaw"
The document contains at least one attachment or enclosure that is a legal document.
"cdt:cdtEnclosedCircular"
The document contains at least one attachment or enclosure that is a circular.
"cdt:cdtEnclosedArticle"
The document contains at least one attachment or enclosure that is an article from a newspaper or similar publication.
"cdt:cdtEnclosedPamphlet"
The document contains at least one attachment or enclosure that is a pamphlet or similar publication.
"cdt:cdtEnclosedAdvertisement"
The document contains at least one attachment or enclosure that is an advertisement of some kind.
"cdt:cdtBornDigital"
"cdt:cdtDatabase"
Database-style documents such as personographies, placeographies, lists of page-images, etc.
"cdt:cdtProsopography"
Biographical data on individuals in the correspondence.
"cdt:cdtVesselography"
Information on vessels mentioned in the correspondence.
"cdt:cdtPlaceography"
Information on geographical locations mentioned in the correspondence.
"cdt:cdtPageImages"
Lists of images of original correspondence-pages linked from the transcriptions.
"cdt:cdtWebContent"
Website pages (introductions, credits, and the like).
"cdt:cdtDocumentation"
Project documentation in XML format.

<ab>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@subtype

att.global.linking
@synch
@sameAs
@copyOf
@exclude
@select

<persName>
No text or whitespace before first child element of a bio persName.
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@when
@notAfter
@resp
@key
@type
"incomplete"
Incomplete biography
We have some information, but a formal bio has not been completed.
"unavailable"
Biographical information is not yet available.
No research has been done to identify or describe this person.
"fn"
First Nations
This individual is believed to be a First Nations person.
@subtype

<surname>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@key
@type
@subtype

<forename>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@key
@type
@subtype

<roleName>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@key
@type
@subtype

<placeName>
This constraint ensures that once a place has been researched, the type attribute is not left on it in error. There appears to be some content in the desc element for this place, so it should not be marked as 'unavailable'. This place description includes references, so it is presumably complete or rudimentary, and should not be marked 'incomplete'. This place description does not include references, so it is presumably incomplete, and should not be marked 'rudimentary'. The value 'rudimentary' is intended for items which are complete, but which might benefit from more research.
@type
"incomplete"
Some content exists, but it is unfinished or inadequate, and will be rewritten in future.
"rudimentary"
A fully-formed entry exists, but the editors believe that more research could provide a better description.
"unavailable"
No content has been written yet.
@when
@notAfter
@resp
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@key
@subtype

<birth>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@resp
@key

<death>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@resp
@key

<geo>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<listPerson>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@type
@subtype

<listPlace>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@type
@subtype

<location>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@type
"path"
@subtype
@when
@notAfter
@resp

<person>
@age
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@resp

<personGrp>
@sex
@age
@size
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<place>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@type
@subtype
@resp

att.datable.custom

att.datable.iso

<code>
@n
@xml:lang
@rendition
@corresp
@facs

att.combinable

att.identified
@ident
@predeclare
@module
@status

att.namespaceable

att.ascribed

att.ranging

att.dimensions
@unit
@quantity
@extent
@precision
@scope

att.damaged
@hand
@agent
@degree
@group

att.breaking

att.datable
@calendar
@period

att.datcat

att.declarable

att.declaring

att.fragmentable

att.divLike
@org
@sample

att.docStatus

att.duration.w3c

att.duration.iso

att.editLike
@evidence
@source
@instant

att.global
@xml:base
@xml:space

att.handFeatures

att.internetMedia

att.media
@scale

att.interpLike
@type
@inst

att.measurement

att.naming
@nymRef

att.pointing
@targetLang
@evaluate

att.pointing.group
@domains
@targFunc

att.readFrom

att.scoping

att.segLike
@function

att.edition

att.spanning

att.timed

att.transcriptional
@hand
@status
@cause
@seq

att.translatable

att.source

att.personal
@full
@sort

<TEI>
@version
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<text>
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@type
@subtype

<body>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<div>
This div with @type should not be nested inside a div with @type . This minute_entry div should be a child of a minutes div. This enclosure_entry div should be a child of an enclosure_list div. This enclosure_transcribed div should be a child of an enclosures_transcribed div. This marginalis div should be a child of a marginalia div. This other_entry div should be a child of an other_files div.
@n
@xml:lang
@rend
@rendition
@type
"correspondence"
"despatch_from_london"
"despatch_to_london"
"enclosure_entry"
"enclosure_list"
"enclosure_transcribed"
"enclosures_transcribed"
"imtAnnotation"
"marginalia"
"marginalis"
"minute_entry"
"minutes"
"other_entry"
"other_files"
"public_offices"
"schedule"
@subtype

<opener>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<closer>
@n
@xml:lang
@rendition
@corresp
@facs

<salute>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<signed>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<facsimile>
@n
@xml:lang
@rend
@rendition
@corresp
@facs

<surface>
@attachment
@flipping
@n
@xml:lang
@rend
@rendition
@corresp
@facs
@ulx
@uly
@lrx
@lry
@type
@subtype

<zone>
@points
@rotate
@n
@xml:lang
@corresp
@facs
@type
@subtype

<fw>
Replace the word "catchword" with the actual catchword as seen on original document. This value cannot be empty. If there is no catchword remove the fw element.
@type
"catchword"
"pageNum"
"sig"
@n
@xml:lang
@rendition
@corresp
@facs
@place

att.global.change

att.coordinated
@start

<listPeople>

<people>

<peopleName>

<list>
@type
"vessels"
A list of vessels
@rend
"bulleted"
A bulleted list
"numbered"
A numbered (ordered) list
"simple"
A list with no list markers (no bullets or numbers)

att.tableDecoration
@cols
@rows

<seg>
@type
"snippet"
This identifies a segment as an "interesting snippet".
"Interesting snippets" are harvested by the build process and turned into a JSON file which is used to drive the home page snippet function.
"disclaimerIP"
This identifies the Indigenous Peoples disclaimer segment in the acknowledgement page.
This segment is placed as a disclaimer on pages containing references to Indigenous Peoples and points them to the Glossary of terms. Segment needs "This document contains" prepended before it.
@xml:id

<orgName>
If there is no descriptive information for an org, please add @type to the orgName.
@type
"incomplete"
Incomplete information
We have some information on this organization, but a formal article has not been completed.
"unavailable"
Information is not yet available.
No research has been done to identify or describe this organization.