<oo>→<dh> Digital humanities

start = poem
poem = element poem { stanza+ }
stanza = element stanza { line+ }
line = element line { text }

Notes:

• Note that poems do not contain lines; the only thing a poem can contain is stanzas. It’s the stanzas that contain the lines.
• It would be odd to have a poem that has zero stanzas or a stanza that has zero lines. This is a textbook case for the plus sign (+) repetition indicator, which means one or more.

start = poem
poem = element poem { stanza+ | line+}
stanza = element stanza { line+ }
line = element line { text }

Notes:

• The only change we’ve made to the preceding example is that we allow either one or more stanzas or one or more lines as the content of a poem. Note that because we use the pipe (the vertical bar), which means either the thing to the left or the thing to the right, we don’t allow a <poem> to contain both stanzas and lines directly. If it has any stanzas, all of its lines must be inside stanzas.
• It would be odd to have a poem that has zero stanzas or lines, or a stanza that has zero lines. This is a textbook case for the plus sign (+) repetition indicator, which means one or more.

start = book
book = element book { intro? , body , conclusion? }
intro = element intro { p+ }
p = element p { text }
body = element body { chapter+ }
chapter = element chapter { title , p+ }
title = element title { text }
conclusion = element conclusion { p+ }

Notes:

• The parts of the book must appear in a particular order. This is the meaning of the comma (,) connector; it means that items separated by commas must appear only in that order.
• Although we use paragraphs in three content models (for intro, chapter, and conclusion), we define <p> only one time. Once you have a definition, you can use it as many times as you need.
• We don’t want to allow books with no chapters, but otherwise we don’t know how many chapters they have. And we don’t want to allow any part of the book (introduction, chapter, or conclusion) to have no paragraphs, but otherwise we don’t know how many paragraphs they might contain. This is a textbook case for the plus sign (+) repetition indicator, which means one or more.

p = element p { mixed { ( ref | date | q )* } }
ref = element ref { text }
date = element date { text }
q = element q { text }

This is the best way to declare mixed content (that is, a content model that contains both text and elements). Reading from the inside out, it says that:

• A paragraph contains a choice (the vertical bar, or pipe, means choice) among references, dates, and quotes. At this point a paragraph must contain exactly one child element, of one of these types. That’s wrong in two ways: 1) we want to allow zero or more child elements, and not require exactly one, and 2) we also want to allow plain text.
• We wrap that choice in parentheses and put a asterisk after the closing parenthesis to say that we make that choice zero or more times. That is, the repetition indicator asterisk (*) tells you that you can repeat the act of choosing among those three element types zero or more times. Now a paragraph may contain any number of any of those three types of elements in any order, but we still aren’t allowing plain text.
• Wrapping all of that in mixed { … } says that you can mix in plain text wherever you want: before, between, or after any of the child elements. This is the final content model we want. Note the extra set of curly braces; the outermost set wraps the entire content model, and the keyword mixed requires its own set of curly braces.

We don’t recommend the following, but it is also syntactically correct to include the plain text as part of the repeatable or-group, as in

p = element p { ( ref | date | q | text )* }

This says that a paragraph can contain any combination of any of the three element types or plain text in any order. That is, it makes the text part of the or-group, instead of using the mixed keyword. We recommend using mixed because when we see it, it proclaims itself immediately to be a mixed content model, whereas with the other solution is more opaque.

Note that if you use the mixed keyword you cannot include the keyword text in your or-group. That makes sense because mixed is already ensuring that plain text can be mixed in among the elements.

start = play
play = element play { title , castList , act+ }
title = element title { text }
castList = element castList { castItem+ }
castItem = element castItem { text }
act = element act { speech+ }
speech = element speech { speaker , mixed { stage* } }
speaker = attribute speaker { text }
stage = element stage { text }

Notes:

• We use comma connectors (,) to separate the content items inside a play because they must occur only in that order. That’s the meaning of the comma: it specifies not just that those things occur, but that they occur in that order.
• We use plus sign repetition indicators (+) to say that we don’t know how many acts a play contains, or how many members there are in a cast, or how many speeches there are in an act, but there must be at least one.
• We use the mixed keyword to describe mixed content, that is, plain text mixed in with elements (in this case, zero or more stage directions in the definition of a speech). Reading from the inside out, we’re saying that a speech contains zero or more stage directions, and plain text can be mixed in before, between, or after those stage directions.

It is not a Relax NG error to model speech as:

speech = element speech { mixed { speaker, stage* } }

It is, however, a mistake because attributes are not mixed into the content the way child elements are; attributes are written inside the start tag. If you write it this way, Relax NG will understand you, but it makes the meaning confusing for a human reader.

text = element text { text }

We usually describe an element inside a content model using the name of the element because that makes our schema easier to understand, but Relax NG does not require that the label that represents the element in the content model match the name of the element in the XML. For example:

document = { preamble, main_text }
preamble = element preamble { text }
main_text = element text { text}

Here we use the label main_text to avoid the error message, but we define that label as referring to an element in the XML that is called <text>. The part of the schema that specifies the element name inside the XML is the part after the keyword element; the label (inside the content model, that is, inside the curly braces, and also to the left of the equal sign) does not have to match the element name. We usually encourage you to have them match because it’s less confusing, but when your element name is a reserved word in Relax NG, changing the name will let you keep it.

p = element p { mixed { footnote* } }  
footnote = element footnote { footnote_p+ }
footnote_p = element p { text }

Earlier we wrote that the label used to represent an element (inside a content model and to the left of an equal sign) does not have to be the same as the element name as it appears in the XML. We exploit that feature here by using different labels for regular paragraphs (which may contain footnotes) and paragraphs within footnotes (which cannot contain footnotes). We define both of those labels (the definitions are to the right of the equal sign) as an element called <p>, which means that we can call them both <p> in our XML and schema validation will enforce the different content models correctly.

You can also work around this limitation by using the Russian doll syntax, where instead of using labels inside the content model and then defining them separately, on separate lines (this is sometimes called salami slicing), you nest the definitions, with their content models, inside one another. For example:

p =
    element p {
        mixed {
            element footnote {
                element p { text }+
            }
        }
    }

Here instead of using a label for footnotes and defining them on a separate line, we embed the definition inside the content model for regular paragraphs. Inside that embedded content model for footnotes we embed the declaration of paragraphs within footnotes. We find this Russian doll syntax difficult to read, so we prefer the label approach, above, but it is valid and idiomatic Relax NG, so you are welcome to use it if you find it clearer than we do.