XML Exercise: Historic Letter

Before you begin

Prepare your workspace: You will be doing most of your coding work for this course in the <oXygen/> XML Editor. This is installed in the campus computer labs, and you may also install it on any other computer(s) you plan to work with this semester. For the very first assignment, here is what you will need:

• Install the <oXygen/> software on your own computer. Follow the instructions and apply the license key we have posted on Canvas.
• Read our Introduction to XML
• Read File Conventions for Canvas Assignments, so you will know how to name this and most other homework files you submit on Canvas.

Goals

This assignment gives you experience with:

1. Writing XML using elements and attributes.
2. Learning how to make XML be well-formed.
3. Making decisions on how to mark information in documents by:
   • Nesting elements that relate to each other.
   • Applying attributes on elements for special indicators (like file folders with labels attached).
   • Writing XML comments to explain something or ask a question about your code.
4. Using basic features of the <oXygen/> software environment.

Scenario

You are collecting letters and artifacts from World War I, and you encounter a collection of letters written by a woman who traveled as a volunteer nurse to France. You find the following as a print transcript. Your task is to code the transcript in XML to mark important information. How you arrange the markup is up to you, but think of the code you apply as the basis for coding many more letters written by the same person.

[Letter from Marian Baldwin, June 30, 1917]

On Board La Touraine,

June 30th, 1917.

Even now that we are out of sight of land, it seems impossible that I am actually off to France
and, for the first time in my life, traveling alone. Everything has happened so quickly since the 
American Fund for French Wounded found an opening for me in Paris that I suppose I am still somewhat 
dazed and bewildered. The fact that I don't know what it will all be like and that I can't look ahead 
makes it easier to be happy and live in the present. Of course I have had a bit of a taste in New York 
of the work that the A. F. F. W. is doing but its Headquarters in Paris will be different in some ways I fancy.

I can't get over how lucky I am to have this chance for I realize how few girls of my age
are getting across, and I understood the grit and pluck which made you encourage me on my great 
adventure and send me along a path which has proved so dangerous of late.

As we drifted down the river, in the sunset glow with two absurd tugs puffing alongside, 
I know that many eyes were moist and that the same thought was in all our minds. How many 
of this ship's company will see that sky-line again! It was very quiet, no one spoke much, 
and, little by little, the glow faded from the sky and one star after another appeared. 
I knew that you would be looking at those same stars down in Lakewood and that your thoughts
and prayers were the same that filled my heart at that moment. Somehow distance does not separate, 
after all.

We waited near the Statue of Liberty until midnight—a rumor had it that a "personage" was 
to come on board. This individual was shrouded in mystery until we put to sea when it was given out 
that the party which had clambered aboard in the night was none other than the Italian Mission. 
Our spirits rose at once for, what with Frank Sayre on the boat and these distinguished Italian gentlemen, 
we shall doubtless be honored by a bigger convoy and so doubly safe. However, thus far we have but two 
destroyers following us. They can be seen distinctly outlined against the horizon, 
one on each side, and seem to be the same somber gray which all ships are affecting in this war. 
A sailor informed me this morning that we weren't in much danger for the first four or five days 
but that after that I might see some excitement. Here's hoping!

I have a small inside cabin and my room-mate is quite a character. She is a native of 
Haiti, voluble and very portly—has four large pieces of baggage in our tiny stateroom, 
wears a costume which resembles a Mother Hubbard and smokes countless thin cigarettes that 
smell like incense! When I appeared, there didn't seem to be much room for me but, as she says, 
luckily I am small, and I was soon tucked into the upper berth with my belongings! She really 
isn't bad and after looking me over carefully told me that she didn't think we would fight and 
from that time has beamed upon me! She is going over to join her son who has been fighting with the 
French since the beginning of the war but will never go back to the Front now, having lost some 
fingers off each hand. She is so thankful, she says, that he hasn't lost more than his fingers. 

[Source: _Canteening Overseas_: 1917-1919, published 1920.] 
            

Coding the letter in <oXygen/>

• First, highlight and copy the text in the box above.
• Open a new XML document in <oXygen/>. Click on the icon at top left that looks like a piece of paper with a folded corner (or go to File and New...), type XML in the filter window, and click the Create button to launch a new XML document.
• Paste in the text you intend to mark up, and begin marking it to apply elements and add attributes.
• Tips:
  • Watch the color of the square in the upper right corner: if it is green, your code is well-formed, but if it turns angry red, you will know there is an error, perhaps tangled tags or a missing angle bracket, or a missing root element.
  • Notice how <oXygen/> generates a closing tag every time you type your own start tag.
  • Try using your mouse to highlight text you want to wrap in an element, and use Control+E in Windows (or Command+E on a Mac) to bring up a window to enter an element name. (You have to add the attributes after you set an element name.)
• Save your work frequently, and name your file using our standard form for homework names.

Suggestions for XML markup

There is no single way to do this exercise, but we want you to think about how you nest levels of information (elements within elements), and the relationship between elements and attributes in XML.

Frequently the XML code we write is designed for digital curation, for preserving and collecting resources. We would certainly not rewrite the base text of a writer's personal correspondence, but we would apply markup around passages, so that our markup supplies some information in a more systematic way. For example, spaces and formatting on the page tell our human eyes something about the document, like how to distinguish each item on a list. That formatting information is not preserved in XML, and so one of the first things we mark are the structural pieces. What are the important parts of this document that you need to distinguish from other parts? Use XML markup to tag those. Then, what is the important information that you can label with markup?

Tips:

• When you make an element or apply an attribute, avoid copying the words and phrases in the text. Think of how your markup can categorize or identify certain kinds of information, to add new value to the text.
• The structure of the document matters: Wrap elements around portions of the document (like the paragraphs, or the dateline) and give them simple, meaningful names. What is the stuff in square brackets at the start and end? Could you set an element to wrap around that material in place of the square brackets?
• Decide on elements and attribute names that you imagine repeating if you were coding many letters in a project. Think about how to keep the coding manageable and not too complicated for others to continue.
• Consider adding elements (perhaps a note with your own text inside) to annotate the document or represent some of the contextual information available with the text. How do you separate your voice, or others' voices from the original letter-writer's voice?

When, where, and how to submit the assignment

Check and make sure you saved your file following our homework file naming rules, including giving it a .xml file extension. Submit your XML file on Canvas on Assignments (for XML Exercise 1) before our next class.