Understanding TEI documents for critical editions

The mind seeks unity.

TEI
├── teiHeader
│   └── basic file description
└── text
    └── body
        └── p [xml:id="p1"]

The mind seeks unity.

This guide is a tutorial. Its purpose is not to provide a complete reference to XML or to the TEI Guidelines. Instead, it introduces the concepts required to build one small, inspectable source document and connect it to ConTeXt.

The same document will then be enriched in the following guides rather than replaced by a succession of unrelated examples.

1. Where this guide fits in the collection

The collection is cumulative. Each guide preserves what the preceding guides have established and adds one new layer.

GUIDE 1
basic TEI document
TEI
├── teiHeader
└── text
    └── body
        └── p [xml:id="p1"]
        │
        ▼
GUIDE 2
add witness declarations
TEI
├── teiHeader
│   └── sourceDesc
│       └── listWit
│           ├── witness A
│           ├── witness B
│           └── witness C
└── text
    └── body
        └── p [xml:id="p1"]
        │
        ▼
GUIDE 3
add basic apparatus relations
TEI
├── teiHeader
│   └── witness declarations
└── text
    └── body
        └── p
            └── app
                ├── lem
                └── rdg
        │
        ▼
GUIDE 4
add complex textual variation
TEI
├── declarations
│   ├── witnesses
│   └── editorial responsibility
└── text
    └── apparatus
        ├── omissions
        ├── corrections
        ├── conjectures
        ├── uncertainty
        └── grouped readings
        │
        ▼
GUIDE 5
process and validate the encoded relations

TEI source
    │
    ▼
Lua processing
├── collect
├── normalize
├── resolve
├── validate
└── diagnose
    │
    ▼
editorial records
    │
    ▼
GUIDE 6
compose the scholarly page

editorial records
    │
    ▼
ConTeXt
├── edited text
├── apparatus
├── witness sigla
├── notes
├── parallel texts
└── page layout
    │
    ▼
typeset critical edition

How to read this diagram. Each guide adds one layer without discarding the preceding ones. Guide 1 creates the TEI container; Guide 2 gives textual sources stable identities; Guides 3 and 4 encode progressively richer textual variation; Guide 5 interprets and validates those relations; Guide 6 turns the resulting editorial structures into a readable scholarly page.

Part I — From plain text to TEI

2. From text to structured source

2.1. Begin with ordinary text

Consider a simple sentence:

The mind seeks unity.

A human reader can recognise this as a sentence and can infer that it might belong to a paragraph, chapter, quotation, or edited passage.

A computer initially receives only a sequence of characters. Nothing in that sequence explicitly says:

this is a paragraph
this belongs to a text
this is part of an edition
this passage has an identity

The first task is therefore not to change the text but to make some of its structure explicit.

2.2. Add markup

Markup adds an explicit structural label:

<p>The mind seeks unity.</p>

The textual content has not changed.

The markup now identifies the content as a paragraph:

paragraph
└── The mind seeks unity.

The start tag

<p>

opens the element, and

</p>

closes it.

2.3. Element, attribute, and textual content

We can now give the paragraph a stable identifier:

<p xml:id="p1">The mind seeks unity.</p>

This small fragment already contains three different kinds of information:

element: p
│
├── attribute
│   ├── name:  xml:id
│   └── value: p1
│
└── textual content
    └── The mind seeks unity.

How to read this diagram. The element identifies a structural unit. The attribute adds information about that unit. The textual content contains the characters represented by the element.

xml:id="p1"

2.4. Markup and typography are different things

The element

<p>The mind seeks unity.</p>

states that the content is a paragraph.

It does not state:

• which font to use;
• which size to use;
• whether the first line is indented;
• what line spacing is required;
• where the paragraph appears on a page.

Those decisions belong to processing and presentation.

STRUCTURED SOURCE
<p>The mind seeks unity.</p>
             │
             │ identifies structure
             ▼
         processing
             │
             │ determines presentation
             ▼
      TYPOGRAPHICAL OUTPUT

How to read this diagram. The structured source says what a piece of content is. A later processing and typesetting layer decides how that structure should be presented.

The same encoded paragraph might later become:

• an ordinary paragraph in a book;
• part of a parallel text;
• a diplomatic transcription;
• a web representation;
• a passage associated with a critical apparatus.

2.5. Read XML as a tree

XML elements may contain other elements:

<text>
  <body>
    <p xml:id="p1">The mind seeks unity.</p>
  </body>
</text>

This nesting produces a hierarchy:

text
└── body
    └── p [xml:id="p1"]
        └── The mind seeks unity.

How to read this tree. body is a child of text; p is a child of body. The nesting of the XML elements creates the hierarchy. Indentation merely makes that hierarchy easier for a human reader to see.

If two paragraphs share the same parent, they are siblings:

body
├── p
│   └── The mind seeks unity.
└── p
    └── Reason examines knowledge.

A processor can use this tree to ask questions such as:

• Which paragraphs belong to the body?
• Which elements have identifiers?
• Which content belongs to a particular paragraph?
• Later, which apparatus entries occur inside a passage?
• Which readings belong to an apparatus entry?

3. From XML to TEI

3.1. XML supplies syntax; TEI supplies a scholarly vocabulary

XML means Extensible Markup Language. It supplies a general syntax for describing structured information through:

• elements;
• attributes;
• textual content;
• nesting;
• identifiers;
• references.

XML itself does not prescribe a vocabulary for textual scholarship.

For example, the following can be well-formed XML:

<edition>
  <metadata>
    <title>A small example</title>
  </metadata>
  <maintext>
    <paragraph>The mind seeks unity.</paragraph>
  </maintext>
</edition>

But well-formed XML is not automatically TEI.

A TEI representation uses the TEI vocabulary:

<TEI xmlns="http://www.tei-c.org/ns/1.0">
  <teiHeader>
    ...
  </teiHeader>
  <text>
    <body>
      <p>The mind seeks unity.</p>
    </body>
  </text>
</TEI>

Both examples use XML syntax. The difference lies in the vocabulary, the documented meanings of the elements, and the structural expectations of the TEI model.

The mind seeks unity.
        │
        │ add markup
        ▼
<p>The mind seeks unity.</p>
        │
        │ XML supplies:
        │ elements, attributes,
        │ nesting and references
        ▼
+-----------------------------+
|             XML             |
|      structural syntax      |
+-----------------------------+
        │
        │ TEI supplies an agreed
        │ scholarly vocabulary
        ▼
+-----------------------------+
|             TEI             |
| TEI, teiHeader, text, p ... |
+-----------------------------+
        │
        │ the editorial project
        │ adds actual evidence
        ▼
+-----------------------------+
|        TEI EDITION          |
| sources, witnesses,         |
| readings, apparatus ...     |
+-----------------------------+
        │
        │ ConTeXt processes
        │ selected structures
        ▼
+-----------------------------+
|       PRESENTATION          |
| text, notes, apparatus, PDF |
+-----------------------------+

How to read this diagram. XML provides the general structural syntax. TEI adds a shared scholarly vocabulary. An editorial project uses that vocabulary to encode a particular body of evidence. ConTeXt then turns selected structures into a typographical presentation.

3.2. The two branches of a TEI document

A minimal TEI document has two principal branches:

                         TEI DOCUMENT
                              │
              +---------------+---------------+
              │                               │
              ▼                               ▼
         teiHeader                           text
   "What is this resource?"          "What text is encoded?"
              │                               │
              ▼                               ▼
         fileDesc                            body
              │                               │
       source information              textual content
              │                               │
        later enriched                  later enriched
              │                               │
              ▼                               ▼
     witness declarations              app / lem / rdg

How to read this diagram. The left branch documents the encoded resource and its sources; the right branch contains the encoded text. Guide 2 will enrich the left branch with witness declarations. Guides 3 and 4 will enrich the right branch with apparatus structures and more complex textual relations.

3.3. Build the minimal TEI header

For the tutorial we need only a very small header:

<teiHeader>
  <fileDesc>
    <titleStmt>
      <title>A small critical-edition example</title>
    </titleStmt>
    <publicationStmt>
      <p>Unpublished teaching example.</p>
    </publicationStmt>
    <sourceDesc>
      <p>Created for the ConTeXt Garden TEI guides.</p>
    </sourceDesc>
  </fileDesc>
</teiHeader>

The three parts used here have distinct functions:

3.4. Add the textual branch

The other main branch contains the encoded text:

<text>
  <body>
    <p>The mind seeks unity.</p>
  </body>
</text>

Its tree is:

text
└── body
    └── p
        └── The mind seeks unity.

Guide 1 deliberately uses only one paragraph. A larger text may later contain front matter, back matter, divisions, headings, quotations, verse, notes, and apparatus entries.

Further reference. For the fuller TEI model of textual structure, including <front>, <body>, <back>, groups, and textual divisions, see TEI P5, Chapter 4: Default Text Structure.

3.5. Create tei-guide-01.xml

Create a plain-text file named:

tei-guide-01.xml

Insert:

<?xml version="1.0" encoding="UTF-8"?>

<TEI xmlns="http://www.tei-c.org/ns/1.0">
  <teiHeader>
    <fileDesc>
      <titleStmt>
        <title>A small critical-edition example</title>
      </titleStmt>
      <publicationStmt>
        <p>Unpublished teaching example.</p>
      </publicationStmt>
      <sourceDesc>
        <p>Created for the ConTeXt Garden TEI guides.</p>
      </sourceDesc>
    </fileDesc>
  </teiHeader>

  <text>
    <body>
      <p>The mind seeks unity.</p>
    </body>
  </text>
</TEI>

This is the first complete TEI source in the tutorial.

Its tree is:

TEI
├── teiHeader
│   └── fileDesc
│       ├── titleStmt
│       │   └── title
│       │       └── A small critical-edition example
│       ├── publicationStmt
│       │   └── p
│       │       └── Unpublished teaching example.
│       └── sourceDesc
│           └── p
│               └── Created for the ConTeXt Garden TEI guides.
└── text
    └── body
        └── p
            └── The mind seeks unity.

How to read this tree. The XML source and the tree are two views of the same structure. The XML is the actual source; the tree makes its hierarchy easier to inspect.

Part II — Stable structure and checking

4. Identifiers and references: from tree to network

So far the document is mainly hierarchical. Critical editions also require relationships between objects that may occur in different parts of the tree.

This is where identifiers and references become important.

4.1. Add a stable identifier

Change:

<p>The mind seeks unity.</p>

to:

<p xml:id="p1">The mind seeks unity.</p>

The paragraph now has a machine-readable identity:

p
├── xml:id: p1
└── The mind seeks unity.

For these guides, identifiers should:

• contain no spaces;
• remain unique within the document;
• remain stable where possible;
• identify an object rather than its changing appearance.

Useful forms include:

p1
chapter-1
witness-A
ms-paris-123
app-0001

Avoid identifiers based on presentation:

first-paragraph-on-page-7
big-red-heading
temporary-item

4.2. Machine identity and printed siglum are different

A manuscript might later have the machine identifier:

xml:id="ms-paris-123"

while a printed apparatus may use the siglum:

P

4.3. References point to identified objects

If an element has:

xml:id="p1"

another element can refer to that object with a value such as:

target="#p1"

Conceptually:

reference
   #p1
    │
    ▼
find xml:id="p1"
    │
    ▼
identified object

How to read this diagram. An identifier declares an object. A reference points back to that declaration. The leading # indicates a reference to an identifier in the same XML document.

4.4. A TEI critical edition is both a tree and a network

Nesting expresses hierarchy:

TEI
└── text
    └── body
        └── p

References express relationships between identified objects.

Looking ahead to Guide 2, a witness declaration and a reading may later be related like this:

                 declaration
            <witness xml:id="A">
                     ▲
                     │
                     │ wit="#A"
                     │
               <rdg wit="#A">
                     │
                     ▼
             reading supported
                by witness A

The two structures operate together:

HIERARCHY                         RELATION

TEI                              witness A
└── text                             ▲
    └── body                         │
        └── p                        │ wit="#A"
            └── app                  │
                └── rdg ─────────────┘

How to read this diagram. The left side tells us where a reading belongs in the document hierarchy. The right side tells us which declared witness supports that reading. A TEI critical edition therefore combines tree structure with reference relationships.

4.5. Update the working TEI file

The current source is now:

<?xml version="1.0" encoding="UTF-8"?>

<TEI xmlns="http://www.tei-c.org/ns/1.0">
  <teiHeader>
    <fileDesc>
      <titleStmt>
        <title>A small critical-edition example</title>
      </titleStmt>
      <publicationStmt>
        <p>Unpublished teaching example.</p>
      </publicationStmt>
      <sourceDesc>
        <p>Created for the ConTeXt Garden TEI guides.</p>
      </sourceDesc>
    </fileDesc>
  </teiHeader>

  <text>
    <body>
      <p xml:id="p1">The mind seeks unity.</p>
    </body>
  </text>
</TEI>

5. Check the document

A usable scholarly source must pass several different kinds of check. These questions must not be collapsed into one.

TEI source
    │
    ▼
+----------------------------+
| 1. XML WELL-FORMEDNESS     |
| Are tags, attributes, and  |
| nesting syntactically      |
| coherent?                  |
+----------------------------+
    │ yes
    ▼
+----------------------------+
| 2. TEI VALIDATION          |
| Is this structure allowed  |
| by the selected TEI model? |
+----------------------------+
    │ yes
    ▼
+----------------------------+
| 3. EDITORIAL CHECK         |
| Does the encoding describe |
| the evidence correctly?    |
+----------------------------+
    │
    ▼
usable scholarly source

How to read this diagram. Passing one level does not guarantee the next. A document may be well-formed XML but invalid TEI. It may also be valid TEI while containing a false scholarly claim.

5.1. Check XML well-formedness

For this working file, check that:

• there is exactly one root element;
• every opened element is closed;
• opening and closing names match;
• elements are correctly nested;
• attribute values are quoted;
• reserved characters are escaped where necessary.

Correct nesting:

<TEI>
  <text>
    <body>
      <p>...</p>
    </body>
  </text>
</TEI>

A useful model is:

last opened
     │
     ▼
first closed

Thus:

open TEI
  open text
    open body
      open p
      close p
    close body
  close text
close TEI

XML names are case-sensitive:

<TEI>
<tei>
<Tei>

are three different names.

5.2. Reserved characters

Some characters have structural meaning in XML.

For example, a literal ampersand in textual content must be written as:

&

so that:

<p>Reason & freedom</p>

represents:

Reason & freedom

Common predefined entities include:

5.3. Well-formed XML is not necessarily valid TEI

This may be well-formed XML:

<TEI xmlns="http://www.tei-c.org/ns/1.0">
  <banana>The mind seeks unity.</banana>
</TEI>

Its XML syntax may be coherent. That does not make <banana> an appropriate TEI structure at this location.

Validation asks a different question: whether the encoded structure conforms to the selected TEI model or schema.

5.4. Valid TEI does not guarantee correct scholarship

Even a structurally valid document may contain an incorrect scholarly claim.

For example, a reading may later be assigned to the wrong witness.

5.5. Practical checklist

Before using ConTeXt, check:

The expected tree is:

TEI
├── teiHeader
│   └── fileDesc
│       ├── titleStmt
│       │   └── title
│       ├── publicationStmt
│       │   └── p
│       └── sourceDesc
│           └── p
└── text
    └── body
        └── p [xml:id="p1"]

Part III — Connect TEI to ConTeXt

6. Load the TEI source with ConTeXt

Guide 6 will develop the complete composition of a TEI critical apparatus. For now we ask only one question:

Can ConTeXt load the TEI tree
and reach the paragraph?

6.1. Keep source and processing separate

The tutorial now contains two files:

              SOURCE                         PROCESSING

       tei-guide-01.xml                  tei-guide-01.tex
       +---------------+                +----------------+
       | TEI structure |                | XML setups     |
       | text          |                | selection      |
       | identifiers   |  ----------->  | formatting     |
       | later:        |      read      | later: Lua     |
       | witnesses     |                | apparatus      |
       | readings      |                | layout         |
       +---------------+                +----------------+
                                               │
                                               ▼
                                       +---------------+
                                       |      PDF      |
                                       | visible text  |
                                       | apparatus ... |
                                       +---------------+

How to read this diagram. The XML file is the scholarly source. The ConTeXt file contains the processing and presentation instructions. The source can therefore remain stable when the typography changes.

6.2. Create tei-guide-01.tex

Save a second file as:

tei-guide-01.tex

Place it in the same directory as:

tei-guide-01.xml

Use:

\xmlregisterns
  {tei}
  {http://www.tei-c.org/ns/1.0}

\startxmlsetups xml:tei:document
  \xmlsetsetup{#1}
    {tei:TEI|tei:text|tei:body}
    {xml:tei:flush}
  \xmlsetsetup{#1}
    {tei:teiHeader}
    {xml:tei:ignore}
  \xmlsetsetup{#1}
    {tei:p}
    {xml:tei:paragraph}
\stopxmlsetups

\xmlregistersetup{xml:tei:document}

\startxmlsetups xml:tei:flush
  \xmlflush{#1}
\stopxmlsetups

\startxmlsetups xml:tei:ignore
  % The TEI header is not typeset in this first test.
\stopxmlsetups

\startxmlsetups xml:tei:paragraph
  \par
  \xmlflush{#1}
  \par
\stopxmlsetups

\starttext

\xmlprocessfile
  {tei}
  {tei-guide-01.xml}
  {}

\stoptext

The explicit namespace registration associates the local prefix tei used in the ConTeXt selectors with the TEI namespace URI declared by the XML document.

6.3. Compile the ConTeXt file

Run:

context tei-guide-01.tex

The intended visible result is:

The mind seeks unity.

The TEI header is deliberately ignored in this first test.

6.4. Follow the processing path

tei-guide-01.xml
        │
        ▼
ConTeXt loads the XML tree
        │
        ▼
teiHeader is ignored in this test
        │
        ▼
text and body are traversed
        │
        ▼
the p element is processed
        │
        ▼
its textual content is flushed
        │
        ▼
The mind seeks unity.

How to read this diagram. ConTeXt does not simply print the XML file as text. It traverses selected structural elements, applies the setups associated with them, and finally flushes the textual content of the paragraph.

This small test does not yet:

• typeset the title in the TEI header;
• apply a complete page design;
• declare witnesses;
• inspect readings;
• build an apparatus;
• use Lua to construct editorial records.

Its only purpose is to establish:

TEI source
    │
    ▼
ConTeXt XML processing
    │
    ▼
visible text

6.5. If the file does not load

Check first:

• the XML filename;
• the directory;
• opening and closing tags;
• nesting;
• quoted attributes;
• the namespace;
• UTF-8 encoding.

7. What you have built

We began with:

The mind seeks unity.

and progressively constructed:

plain textual content
        │
        ▼
<p>The mind seeks unity.</p>
        │
        ▼
XML element + attribute + hierarchy
        │
        ▼
TEI vocabulary
        │
        ▼
TEI root + header + text
        │
        ▼
xml:id="p1"
        │
        ▼
checked structured source
        │
        ▼
ConTeXt loading test
        │
        ▼
visible text

How to read this diagram. The visible output is intentionally simple. The important achievement is that the sentence now belongs to a structured, identified, reusable TEI document whose presentation is controlled separately by ConTeXt.

The architecture now looks like this:

                 TEI DOCUMENT
                      │
        +-------------+-------------+
        │                           │
        ▼                           ▼
   teiHeader                       text
 documentation                  textual data
        │                           │
        │                           ▼
        │                          body
        │                           │
        │                           ▼
        │                     paragraph p1
        │
        +-------- future guides --------+
                     │
             +-------+-------+
             │               │
             ▼               ▼
         witnesses       app / lem / rdg
             │               │
             +-------+-------+
                     │
                     ▼
                Lua / ConTeXt
                     │
                     ▼
              scholarly page

How to read this diagram. Guide 1 has established the upper part of the structure: the TEI container, the documentary header, the textual body, and one identified passage. The lower part shows the layers that the next guides will add.

8. Continue with Guide 2

The working document currently looks like this:

TEI
├── teiHeader
│   └── fileDesc
│       └── sourceDesc
│
└── text
    └── body
        └── p [xml:id="p1"]

Guide 2 will enrich the documentary branch:

TEI
├── teiHeader
│   └── fileDesc
│       └── sourceDesc
│           │
│           └── WITNESS DECLARATIONS       ← GUIDE 2
│
└── text
    └── body
        └── p [xml:id="p1"]

How to read this diagram. Guide 2 does not replace the document built here. It adds declarations for the textual sources on which the edition depends, while the existing textual branch remains in place.

The cumulative route is therefore:

Guide 1
TEI container + identified passage
     │
     ▼
Guide 2
witness identities
     │
     ▼
Guide 3
basic apparatus relations
     │
     ▼
Guide 4
complex textual variation
     │
     ▼
Guide 5
processing + validation
     │
     ▼
Guide 6
scholarly page composition

Next: Declaring witnesses in TEI critical editions

Related pages

• Building critical editions from TEI XML
• Glossary of terms used in the TEI XML critical edition guides
• TEI XML
• XML
• ConTeXt and Lua programming
• Processing XML with Lua
• Typesetting a TEI critical apparatus with ConTeXt