<oo>→<dh> Digital humanities

Preliminary instructions

The goal of this test is to create a well-formed Relax NG schema using a XML document that we will supply for you. Here’s how to get started:

1. Open the XML document at (lilacs_lyrics.xml) in <oXygen/>. You can open it directly from the Internet by hitting Ctrl+u (Windows) or Cmd+u (Mac) in <oXygen/> and then copying and pasting the URL into the Open URL dialog box.

2. The XML document for which you will be creating a schema is the song Lilacs from Dave Malloy’s musical Preludes. You can hear it performed on YouTube (it’s really a very lovely song, so we highly recommend checking it out!).

3. Use File → Save As in the <oXygen/> menu to save the XML file locally to your computer.

4. Create a new Relax NG compact syntax document and save it to your computer in the same directory as the XML, making sure that you follow our file-naming conventions, as you would for any assignment in this class.

5. After you’ve saved both the XML song file and the new Relax NG file, click into the XML file and then use the Document → Schema → Associate Schema menu options to associate your XML with your Relax NG. The schema won’t be valid yet, which means that XML will also show a red square, but after you’re done with this next task, you will have two beautiful green squares.

Your task

Create a Relax NG schema that validates the XML file that we provide. This test is open book, but you can’t receive help from another person. Here are some more details:

• You can’t change the XML exceptfor having <oXygen/> add the association line for the schema.

• Your schema should make good use of effective comments that 1) guide the reader through the structure of the schema file and 2) explain the reasons behind any design decisions that aren’t self-explanatory. One guideline for explanatory comments is that although the code itself can often communicate what it does (by using self-documenting names), the code can’t explain why you did one thing instead of another. Documenting what isn’t self-explanatory, then, most often means explaining the why.

• We recommend developing your schema step by step, using placeholders, as we demonstrated in class. This approach lets you focus on a small part of the functionality at a time, so that if something doesn’t work, you’ll know where to look to fix it.

• <oXygen/> cannot validate any part of the XML if you have an invalid schema (that is, if the schema file shows a red square). To work around that limitation and check at least the parts of your schema that you think are correct, you can put a placeholder like text in the content model for the statement you’re stuck on so that the schema will be valid and <oXygen/> can then use it to validate the XML. This is similar to the use of placeholders for incremental development that we describe above. <oXygen/> will reports validation errors in the XML for the items with the placeholder, but at least you’ll be able to verify whether your other schema statements are doing what you think they should do, and you can then come back to the problematic bits later. The point is that you don’t want a single sticking point to keep you from validating at least parts of your XML.

• Your schema should be applicable to multiple documents of the same type, and whether that means all songs in this musical or, more broadly, songs from many different musicals is up to you (so document your decision in a comment in your schema!). For example, if you decide that you (hypothetically) want to mark up the lyrics of every song from this musical, Natalya and Rach aren’t the only characters, so consider that when defining attributes in your schema. And we can’t say this often enough: Whatever decisions you make, be sure to document them with a comment.

If you get stuck, feel free to ask a question in the #relax-ng channel in our Slack. Don’t be shy about doing that; if you have a question, it’s likely that someone else will have the same question. We can’t write the schema rules for you, but there’s a lot we can and will do to point you in the right direction.