2.1.1. 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.

2.1.2. 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.

2.1.3. 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.

5.1.1. 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.

5.3.1. 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.

5.3.2. 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.

5.3.3. 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.

5.3.4. 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”).

1. After clicking ‘Export…’ and navigating to your ‘collection’ folder, you will find the first image named co_305_01_00001r.jpg.
2. 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.
3. 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.

5.3.5. 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

5.3.6. 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.

5.3.7. 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.

5.3.8. 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!

5.3.9. 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.

5.3.10. 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).

5.3.11. 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.

5.3.12. 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.

• [$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.

5.3.13. 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.

5.3.14. 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.”

5.4.1. 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.

1. 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.’
2. 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:

   

3. Upload your folder full of images to your personal folder on the ‘coldesp’ server.
4. 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.
5. Make backups of your files in your prefered location(s).
6. 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.’

6.4.1. <biblScope> tags

6.4.2. <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.

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.”

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.

6.5.1. 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.

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

6.5.1.3. 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.

6.5.2. 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.

6.5.3. 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:

6.5.4. 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:

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.

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

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.

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

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.

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

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.

6.5.8. 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.

6.5.9. 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.

6.6.1. 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.

6.6.2. 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: †

6.6.3. 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: ⁜

6.7.1. CSS: general application

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.

6.7.2. CSS: block quotations

6.7.3. CSS: bold text

6.7.4. CSS: centre text

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

6.7.5. CSS: italic text

6.7.6. CSS: list

6.7.7. CSS: multiple rules in one tag (a rulesheet)

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

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

6.8.2. 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.

6.8.3. Ranges, with from and to

6.8.4. Non-consecutive ranges

6.8.5. 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.”

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.

6.8.6. notBefore and notAfter tags

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.

6.8.7. 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.

6.8.8. Dates in the general sense: no fixed date

6.8.9. 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:

ABd

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.

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

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

6.9.1. Indigenous Peoples <ip> tags

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.

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

Individual:

Group:

6.9.2. 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.

6.9.3. 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.

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.

6.9.4. Links: external (to pages outside the Despatches site)

6.9.5. Links: internal (to other Despatches documents)

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:

6.9.6. 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).

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.

6.9.7. 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.

6.9.8. 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.

6.9.9. 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).

6.9.10. 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.⚓

6.9.11. Notes

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

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.

6.9.11.1. 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:

1. 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>.
2. 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.

6.9.12. 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.

6.9.13. 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…

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

6.9.14. Sex attribute

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.

6.9.15. 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):

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

6.9.16. 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:

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

6.9.17. 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:

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:

Further reading on apparent errors can be found here.

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).

6.9.18. Strange strings, funny tags, and other legacy issues

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.

6.9.19. 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:

(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.

6.9.20. 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.

6.9.21. 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.

6.9.22. Unclear tag

6.9.23. 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!

7.1.1. 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)

7.1.2. 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).

7.7.1. 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).

7.7.2. 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.”

7.7.3. 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).

7.7.4. 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:

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.

7.7.5. 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

7.7.6. 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)

7.7.7. 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.

7.13.1. 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

7.18.1. <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).

7.18.2. 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.

8.3.1. 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:

8.3.2. Examples of endnotes

8.3.2.5. Website source examples

8.3.2.5.1. 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:

8.3.2.5.2. 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:

8.3.2.5.3. 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>

8.3.3. 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.

8.3.4. Multiple citations

8.3.5. Multiple citations in one note

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

8.3.6. Multiple and repeating citations

9.2.1. Before you write abstracts

9.2.2. 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:

9.2.2.2. 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.

9.2.2.3. 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.

9.2.3. 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.

9.2.4. 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)].

9.2.5. 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

9.4.1. 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:

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

*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.

9.4.2. 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.

10.1.1. 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.

10.1.2. 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.

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.

10.1.3. 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.

10.1.4. 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.

10.2.1. 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

10.2.2. 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.

10.2.3. 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

10.2.4. 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.

10.2.5. 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.

10.2.6. 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.

10.2.7. 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.

10.2.8. 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.

10.3.1. 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.

10.3.2. Biography markup for citations

See the Basic Endnotes section.

11.2.1. How to tag places that appear in the correspondence files

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.

11.2.2. 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!

11.3.1. How to tag placeographies in the places.xml file

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.

11.3.2. 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 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.

11.3.2.2. 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.

11.3.2.3. 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:

11.3.3. How to map a location with the Mercator Vertexer tool

1. 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.

   

2. 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.
3. Assuming you’re working on a computer with two monitors, locate Bristol in Google Maps on one monitor.
4. 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.
5. 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.

   

6. 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.

11.3.4. 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>

12.1.1. 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:

12.2.1. How to tag vessels that appear in the correspondence files

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).

12.2.2. 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!

12.3.1. 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.

12.3.2. 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>

14.2.1. 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.

14.2.2. 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.

14.2.3. More regular expression examples

1. The example below finds instances of ‘1861’ excluding ‘1861’ with a dash, quotation mark or ‘</’ immediately after it (e.g. 1861</).

   1861(?!</)(?!-)(?!")⚓

2. 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⚓

3. The example below is to find the word ‘Instant’ when it’s the first word on a line.

   ^Instant ⚓

4. The example below is used to find a name element followed by a new line that starts with ‘TFE’ (initials).

   <name>(\n)^TFE⚓

5. 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 ⚓

6. 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 ⚓

7. The example below finds all elements that contain only two words.

   >[A-Z][a-z]+\s[A-Z][a-z]+<⚓

8. 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}⚓