This is a very simple example that we've cooked up to demonstrate some basic markup; it has some basic features that are common to prose documents, such as: a heading a few paragraphs a list some embedded features like names, quotations, foreign words It's worth noting before we even look at the markup that there's already structure being expressed here. We notice from signals conveyed by typography and layout what structure is being conveyed. Part of what we're doing in our XML markup is translating these typographical cues into a form that a computer can understand.

This passage contains some more detailed encoding that the TEI provides in bold.

There are a few things to note about this passage. First is that the said element has replaced the quotes in the previous passage. This encoder decided that the information said provides is enough to omit the quotations. This is not something you need to do. If you are interested both in the information that the said element provides and the typographical cues of quote marks in the original passage, you can encode both the said and the quotes. However, if you aren't interested in the different ways of marking spoken passages, you can proceed as the encoder of this passage did.

The other thing to note is the double usage of the xml:lang attribute. In both cases, xml:lang is indicating that the content of the element is in French. Note that it is applied to the said (the spoken passage is in French), and a catch-all foreign element (which just says, the content of this element is French).

Here we have even more elements provided by the TEI, once again in bold. These are the most generic elements for capturing quotations and citations.

We've added an epigraph which contains a quote as well as the bibliographic information about where the quote came from (in bibl, title and author).

We can also record quotes and the names of works within the running text of the chapter. So, for example, we have the quote from Hamlet marked, as well as the reference to the title. Note also that we have quote nested inside said, since the quote was spoken. Both of these elements can be nested within each other.

Note that all of the possible encodings we've recorded in the past three slides are valid. Depending on the aims of your project, you could have employed any of the above encodings—or even more complex ones, if your project is invested in recording other textual features.

Let's take a step back now to see how a piece of text fits into a TEI document. This is a very basic example of a complete TEI document. We can see that the TEI element is the root element, and that we also have a required element, teiHeader (the content of teiHeader is omitted here, but it contains metadata about the text and encoding, among other things*). We also have the text element which contains our transcription and markup of the text. This is basic the structure of how complete TEI documents are represented.

* For more information on the teiHeader, see the Contextual Encoding Primer

Here, we will take a minute to zoom in on the text element. As in the previous example, we have the required body element. But we've also added the optional elements front and back. These elements are where you encode the front- and back-matter (so introductions, notes to the reader, epilogues, indices, etc.)

Next we'll look at document structures for some common types of texts in the humanities.

Poetry is encoded using the lg (or line group) element. Each lg must contain either l (the individual lines) or more, nested lg elements. Think of the lg element as being like a poetic div, and all of the l elements as poetic p elements. Like p, l contains text and smaller, phrase-level elements. lg can also contain head (just as div can). You can also use the type attribute to specify what type of line group you are encoding. In the example here, we have values on the type attribute that specify that the whole poem is a sonnet, and that the sonnet is divided into two quatrains and a sestet.

One thing that this example does not show is that lg and l can be intermixed within outer, wrapper lg elements. So if, for example, your poem contained mostly couplets that you didn't want to mark as individual lg elements, but some tercets that you did want to mark, you could put lg type="tercet" in the middle of a sea of ls. This differentiates lg from div, since div cannot float in the middle of smaller-level elements, like p.

One of the benefits of the TEI is that it allows you to group elements together on the basis of semantics, rather than rendition. This comes in handy when you want to encode drama. Although there are no physical cues in the manuscript indicating that you should group a speaker tag and the speech together, you still will want to explicitly associate these two things. This is something that HTML does not allow us to do, as we saw previously.

The TEI sp tag allows us to say, all of the content of this element is a part of one dramatic speech. The speaker tag contains the speaker label, and we use either p or lg to encode the content of the speech (depending upon whether the speech is in prose or verse).

Additionally, the who attribute allows us to refer specifically to one character. As you have probably seen, speaker labels in manuscripts are sometimes misspelled, have variant spellings, or are just plain inaccurate. The who attribute points to one stable person in the castList, so that you have a regularized way of saying who is speaking, rather than relying on the sometimes-inaccurate speaker labels.

So, for example, if Dinah in the example were sometimes spelled Dina or accidentally called Donna, you would still be able to refer to the static entry of #spDin in the cast list.

Letters have the opener and closer elements to encode features like salutations (salute), datelines (dateline), and signatures (signed). The TEI constrains where elements like opener and closer can go. opener must be the first (or almost the first) thing encoded in the letter, and the closer must be the last (or almost the last). If the letters you want to encode follow a different structure than is allowed by the TEI, you will need to customize the TEI* to allow for these variant structures.

*See our Customization Primer.

Now that we've seen some basic document structures, let's dig into some basic elements for phrase-level encoding. You can use phrase-level elements to encode names and references to things, such as persName, placeName, orgName, title, and rs (which stands for referencing string, and is used to encode references to places, persons, etc. that aren't explicitly named, e.g. the states as a reference to the US.).

There are also elements, like date and measure that allow you to do more analytical markup. So, for example, use a regularized unit for measure that will allow you to compare items that use different, non-standard, or antiquated units.

date allows you to encode references to specific days (or months or years) on the calendar. Since the transcribed information is not always enough, the when attribute allows you to create a regularized yyyy-mm-dd version of the date. In this way are able to remain true to the text by transcribing content, but you can simultaneously regularize the dates so that you can perform analysis on it (e.g. creating timelines).

You can also encode specific linguistic features using TEI's phrase level elements. As we saw earlier, you can use the foreign element, the xml:lang attribute (or both!) to state that a text is in a language that is not the text's main language. You can use soCalled and emph for different rhetorical features.

Occasionally, you will encounter words or phrases that you want to mark, but have no specific element to use. In these cases, you can use hi (for elements that are highlighted for reasons we don't want to mark), seg (for words and phrases that we want to mark, but have no better vocabulary to use), and anchor (for anchor points in the text).

Let's move into some more complex encoding situations. Sometimes when we transcribe a text, we come across instances when we want to edit, correct, update or otherwise change the text. However, when we do this, we usually still want to maintain what the original says. In these cases, we use the choice element.

The enclosing choice element allows us to create parallelism between the two elements that are enclosed. It doesn't actually violate the ideal document tree, but it does make it slightly more complex: almost as if a twig has split and then rejoined.

The choice approach is useful for smaller and more local examples of parallel text. There are a number of local editorial changes that are often made in the process of transcription and editing. These are processes of regularization and correction that are often done silently and noted in an introduction, such as correction of typographical errors in the source, regularization or modernization of spelling and typography, and expansion of abbreviations.

In print-based editing, these choices are exclusionary; whichever kind of reading you decide to show the reader, its complementary version has to be suppressed (it could be indicated in a note or an appendix but it can't typically be displayed as part of the regular reading surface).

In an XML transcription, however, it's possible to represent both (or in principle multiple) readings in a data structure that shows their parallelism and treats them as alternatives, which can then be chosen (displayed, searched, etc.) when desired.

In the example above, the word boũde is expanded to bounde and the original delyuered is regularized to the modern delivered. In both of these cases, the choice element is signifying that one of the nested elements should be taken into account when reading (i.e. the sentence doesn't read not be boũde bounde also, but rather either not be boũde or not be bounde). This type of encoding allows for many things. For example, you could display provide different options for display on your interface. A graduate student could read the original, and an undergraduate could read the more regularized and updated version.

The example at the bottom is a bit more complex, but it shows the versatility of the choice element. In the example, the text has both a typo, and is in abbreviated form. The markup shows that you can nest choice inside of itself to account for the sic (error) and corr (correction), while still using the abbr (abbreviation) and expan (expansion) elements. The markup shows (in order): the incorrect abbreviated, correct abbreviated, incorrect expanded, correct expanded choice.

The TEI also provides us with mechanisms for showing how documents changed as they were revised. The add and del elements are methods for showing additions and deletions to the text over time.

The subst (substitution) element is a way of showing that there are one or more deletions from the text accompanied by one or more additions that are meant to be understood together. So for example, the writer here crossed out an and wrote in the as a substitution; these two revisions are meant to be thought of as one editorial gesture, so they are grouped.

If you have extensive handwritten portions of your documents, you may want to take a look at our Manuscript Encoding Primer.

Because the transcription of manuscript materials (and often printed texts as well) involves significant efforts of decipherment and in many cases conjecture or interpretation, and also because primary sources are informationally complex (authorial revision, erasures, missing letters, illegible passages, etc.), a responsible transcription needs to capture not just the end product but also information about the process and the editorial decision-making. It must not just produce a clean, organized transcription, if that comes at the expense of preserving information that was difficult or unclear.

There are already several methods for indicating editorial uncertainty or conjecturing in print: carets and brackets for marking insertions and deletions, italics to indicate unclear text, footnotes to indicate hypothetical readings or to describe damaged sections. In text markup, the goal is to formalize as much of this information as possible and represent it systematically and to classify the reasons for illegibility (where possible), to formalize the rationales for determining whether a given letter is illegible or simply unclear.

In this example, we use unclear, supplied, gap (with attributes: reason, extent) to indicate as much about this manuscript as we can.

We do this with the goal of making it possible to control the display of the reading surface of the text. For example we might show or hide the deleted words and hypothetical readings. If your project has the resources or time, perhaps you could even let the reader control the threshold of conjecture at which readings are displayed or hidden (e.g. "only show me things you're really certain about").

In addition to using the elements we've discussed to acknowledge transcriptional complexities, you can also use attributes to provide further nuance.

So, for example, you can use the hand attribute to indicate who is making an addition or deletion to a text. You can use the place attribute to state where the addition or deletion was marked, or the rend attribute to say how the marking was made (e.g. cross-out, scribble, underlined text).

You can also provide the reason attribute to state what caused the text to become illegible or unclear. The value for these could be anything from poorly-inked-type to coffee-stains. Additionally, you can state the extent to which the text is missing. So for example, if a page was ripped out of the book you're encoding, you could explicitly state that the extent of missing text was 1 page.

The resp, evidence, source, and cert attributes all allow you to say something about the text in your transcription. The resp attribute allows you to state who is responsible for that specific reading of the text. The evidence attribute says something about the nature of the evidence that supports that reading (the TEI recommends internal, external, and conjecture as values). The source attribute allows you to say where the text was supplied from, if you used external evidence (e.g. a different edition of the book). Finally, cert allows you to state your certainty about whether the reading you've made was accurate.