Building critical editions from TEI XML

Unofficial ConTeXt Wiki mirror

Last modified: 2026-08-30

🚧 Under construction — This page and its subpages are currently being revised. Contributions are welcome: feel free to edit and improve them.

Building critical editions from TEI XML with ConTeXt

Glossary  ·  Start with: Guide 1  ·  Final guide: Guide 6  ·  ConTeXt-only route: Building a critical apparatus with ConTeXt

From textual scholarship to structured editorial data

A critical edition is both a work of textual scholarship and a work of publication.

The editor studies the surviving forms of a text, compares their readings, identifies agreements and differences, and decides how the evidence should be represented. That evidence must then be organised, checked, transformed, and finally presented to the reader in a usable typographical form.

At first sight, this may seem mainly to be a problem of notes. Critical apparatus entries are often printed at the bottom of the page, and ConTeXt provides powerful mechanisms for placing and formatting such material.

But a critical apparatus is not merely a specialised footnote system. It is the visible result of an underlying editorial structure: witnesses, lemmas, readings, omissions, corrections, conjectures, relationships, and editorial decisions.

This is why TEI XML becomes relevant. The progression developed in these guides is: 

note
  ↓
critical apparatus
  ↓
structured editorial data
  ↓
XML
  ↓
TEI
  ↓
processing and validation
(Lua where useful)
  ↓
ConTeXt typesetting

How to read this diagram. The stages do different jobs: editorial observations become explicit structured data, that data can then be processed, and ConTeXt turns the result into a reader-facing form. Lua is shown as a possible processing layer, not as a compulsory stage between TEI and ConTeXt.

The essential distinction is therefore between the scholarly data of the edition and the typographical form in which those data are presented.

This page introduces those stages and explains how they belong together. It then directs readers to a glossary and to six specialised guides.

1. From notes to critical apparatuses

ConTeXt provides a wide range of mechanisms for placing annotations outside the main flow of a text. Notes may appear at the bottom of the page, at the end of a chapter or document, in the margin, in parallel columns, or in separately collected lists.

From a typographical point of view, a critical apparatus may therefore seem to belong to the same general family of objects as footnotes and endnotes: a sign or a passage in the text directs the reader to information placed elsewhere on the page or in the document.

This similarity is real, but only partial.

1.1. What is a note?

An ordinary note is usually attached to a point in the text and contains a relatively independent piece of information. It may provide:

For example: 

The date of the first edition remains uncertain.¹

1. The surviving title page may belong to a later issue.

The note is related to the main text, but its contents can generally be read as a separate statement.

1.2. What is a critical apparatus?

A critical apparatus records textual variation.

Suppose that three witnesses preserve different forms of the same sentence: 

A  The mind seeks unity.
B  The soul seeks unity.
C  The mind desires unity.

An editor who prints the text of witness A might produce the following apparatus entries: 

mind] soul B
seeks] desires C

These entries may occupy the same physical area as footnotes, but they do not have the same internal structure.

An ordinary note generally adds a comment to a passage. A critical apparatus entry records a structured relationship between several textual forms.

It may:

The problem is therefore not only where the note should be placed.

It is also how the textual evidence should be represented.

Stage reached. A critical apparatus may occupy the same physical area as ordinary notes, but its underlying information is different. We must therefore move from the question of where to place a note to the question of how to represent textual evidence.

2. The apparatus as structured editorial information

Consider the compact apparatus entry: 

mind] soul B

A reader familiar with critical editions may understand that:

These relationships are expressed through typographical convention. They are not explicitly identified within the printed character string.

A fuller description of the same entry would be: 

apparatus entry
├── lemma
│   ├── text: mind
│   └── witness: A
└── variant reading
    ├── text: soul
    └── witness: B

The compact printed form and the expanded description contain related information, but they serve different purposes.

The first is designed for economical reading on a printed page.

The second reveals the internal structure of the editorial record.

This distinction becomes increasingly important when an edition contains hundreds or thousands of variants, several classes of witnesses, multiple apparatuses, or several intended forms of publication.

2.1. Description and presentation

ConTeXt can handle the typographical side of a critical edition:

A critical edition also requires a way to describe the underlying textual relations independently of their final appearance.

This is where structured data become useful.

The combination of structured data and ConTeXt separates two operations that are often mixed together in a manually prepared edition:

This separation does not imply that the two operations are unrelated.

Editorial interpretation determines what must be displayed. Typographical design determines how readers can perceive the relationships established by the editor.

The two layers cooperate, but they do not perform the same task.

Guiding principle. The TEI source records the editorial relationships; ConTeXt determines how those relationships are presented. Separating description from presentation makes the edition easier to verify, transform, and redesign.

2.2. Why not store only the printed apparatus?

An apparatus entry can be written directly as a formatted character string: 

mind] soul B; understanding C

For a small edition, this may be entirely sufficient.

For a larger or reusable edition, however, the editor may later need to:

If the editorial information exists only as a preformatted string, such operations require the string to be interpreted or rewritten.

If the lemma, readings, and witnesses have been recorded as distinct components, the same information can be transformed into several forms.

For example, one structured record might produce: 

mind] soul B; understanding C

or: 

mind A] soul B; understanding C

or: 

Witness B reads “soul”, while witness C reads “understanding”,
instead of “mind”.

The editorial data remain the same. The rules of presentation change.

Do not encode typography as evidence. A string such as mind] soul B is a useful printed result, but it is a poor substitute for separately encoded lemmas, readings, and witness references.

3. Why TEI XML is useful

3.1. What XML contributes

XML stands for Extensible Markup Language.

XML is not a theory of textual criticism and does not by itself define a critical apparatus. It provides a general syntax for identifying the components of structured information.

For example: 

<reading witness="B">soul</reading>

This markup identifies:

XML documents are constructed from elements, attributes, textual content, and hierarchical relationships.

An imaginary XML representation of an apparatus entry might therefore be: 

<apparatus>
  <lemma witness="A">mind</lemma>
  <reading witness="B">soul</reading>
</apparatus>

This is structured XML, but it is not yet TEI.

XML tells us how a vocabulary may be written. It does not determine which vocabulary textual editors should use.

3.2. What TEI adds to XML

TEI stands for the Text Encoding Initiative.

The TEI Guidelines define a shared vocabulary and a set of recommendations for representing texts and textual scholarship in XML.

The expression TEI XML therefore combines two levels:

TEI does not treat a variant reading as an already formatted footnote. It represents it as structured data.

A critical passage may be encoded with:

A basic TEI apparatus entry may look like this: 

<app>
  <lem wit="#ms-A">mind</lem>
  <rdg wit="#ms-B">soul</rdg>
  <rdg wit="#ed-C">understanding</rdg>
</app>

Here:

The same encoded information can be used to produce different outputs:

TEI describes the textual relationships. It does not prescribe one final visual form for them. 

              XML
               │
               │ supplies syntax
               â–¼
       elements + attributes
               │
               │ TEI adds a shared
               │ scholarly vocabulary
               â–¼
              TEI
               │
       app / lem / rdg / wit
               â–¼
      editorial relationships

How to read this diagram. XML provides the general language for structuring data. TEI does not replace XML: it supplies a documented scholarly vocabulary and model expressed in XML.

Why TEI rather than arbitrary XML? TEI supplies a documented scholarly vocabulary and a shared structural model. This allows the encoded apparatus to be understood, validated, and reused beyond the conventions of one private file.

4. Processing and typesetting

4.1. What Lua can do between TEI and ConTeXt

A TEI document contains structured editorial information, but that information does not automatically determine the exact form of the printed edition.

Before typesetting, the data may need to be:

Lua is integrated into LuaMetaTeX and is therefore directly available to ConTeXt.

It can be used to:

Lua should not be understood as a substitute for TEI.

TEI records the editorial structures. Lua processes them.

Nor does Lua replace ConTeXt. ConTeXt remains responsible for the composition and visual presentation of the edition.

The relationship is better represented as a choice of processing paths: 

                         TEI XML
                            │
                 ┌──────────┴──────────┐
                 │                     │
                 â–¼                     â–¼
        direct XML processing     Lua processing
        with ConTeXt setups       when more control
                 │                is required
                 │                     │
                 └──────────┬──────────┘
                            â–¼
                         ConTeXt
                            │
                            â–¼
                   typeset edition

How to read this diagram. Lua is not a compulsory stage between TEI and ConTeXt. Simple mappings can be handled directly with ConTeXt XML setups; Lua becomes useful when the encoded data must be collected, validated, reordered, grouped, or transformed before typesetting.

Technical note. ConTeXt can process XML directly. Lua is an optional processing layer that becomes especially useful when a project needs systematic validation, normalization, selection, grouping, or transformation.

4.2. What ConTeXt contributes

ConTeXt provides the programmable typesetting environment in which the structured editorial information is turned into a readable edition.

It can determine:

ConTeXt also provides XML-processing facilities. It can identify TEI elements, attach setup commands to them, retrieve attributes, and combine XML selection with Lua processing.

ConTeXt therefore acts primarily at the level of typographical presentation, but it can also participate in the interpretation and transformation of the TEI structure.

4.3. Complementary responsibilities

Layer Principal responsibility
Textual scholarship Establish the witnesses, readings, relationships, and editorial decisions.
TEI XML Record those textual and editorial structures explicitly.
Lua Inspect, validate, select, group, and transform the encoded data.
ConTeXt Compose and present the resulting edition.

The boundaries are not completely rigid. ConTeXt can perform data-processing tasks, and Lua can produce typographical instructions. Nevertheless, the distinction helps clarify the architecture of a critical-edition project.

For example:

Guiding principle. Editorial changes should not have to be expressed as typographical changes, and typographical redesign should not require the scholarly data to be rewritten.

4.4. From the note area to a model of textual variation

A critical apparatus may be printed in the same area as footnotes, but its source is not merely a note mechanism. It is a structured model of textual variation.

The collection therefore follows one continuous path: 

textual evidence
        ↓
TEI encoding
        ↓
selection, validation, and transformation
        ↓
ConTeXt typesetting
        ↓
readable critical edition

The six guides develop this path progressively, from the first TEI document to the final apparatus.

5. How to use this collection

This is an orientation and explanation page. Its purpose is to explain why a critical apparatus may be represented as structured TEI XML data, how the principal layers of the workflow relate to one another, and where to go next.

It is not intended to replace the specialised resources in the collection.

The collection contains three kinds of resource:

Readers who are unfamiliar with the editorial or technical vocabulary should consult the glossary. Readers who are completely new to XML or TEI should then continue with Guide 1.

The guides are progressive, but they are also designed to remain useful as separate problem-oriented pages.

Readers who wish to construct an apparatus directly in ConTeXt, without first encoding the textual data in TEI XML, should instead begin with:

5.1. Glossary

The collection uses terminology from textual criticism, XML, TEI, Lua, and ConTeXt.

Rather than redefining those terms on every page, the collection maintains a separate reference resource:

Glossary

Use it whenever a term such as witness, lemma, xml:id, <rdg>, or XML setup is unfamiliar.

Documentation role. The glossary is a reference resource; this page is an explanation and orientation resource. Keeping those roles separate avoids turning the overview into a second glossary.

6. The six guides

The six guides follow the construction of a critical-edition workflow from the first TEI document to the final typeset output. 

GUIDE 1
TEI document
    │
    â–¼
GUIDE 2
witness declarations
    │
    â–¼
GUIDE 3
basic apparatus entries
    │
    â–¼
GUIDE 4
complex textual variation
    │
    â–¼
GUIDE 5
processing and validation
    │
    â–¼
GUIDE 6
ConTeXt typesetting

How to read this diagram. Each guide adds one new layer without discarding the preceding ones. The TEI source grows from a minimal document into structured editorial evidence; processing becomes more systematic; the last guide turns the resulting information into a scholarly page.

6.1. Guide 1: Understanding TEI documents for critical editions

Question: What kind of document will contain the later editorial data?

Guide 1 introduces the basic structure of XML and TEI: elements, attributes, hierarchy, the TEI header, the textual body, identifiers, references, well-formedness, and validation.

Stage reached. The reader has a small, well-formed TEI source with the basic structure that ConTeXt can load and inspect.

Guide 1: Understanding TEI documents for critical editions

6.2. Guide 2: Declaring witnesses in TEI critical editions

Question: How can manuscripts, editions, and other textual witnesses be identified once and then referenced consistently?

Guide 2 introduces witness declarations, stable XML identifiers, editorial sigla, source descriptions, and the distinction between declaring a witness and referring to it from later apparatus data.

Stage reached. The TEI document contains a coherent witness registry whose entries can be cited by later lemmas and readings.

Guide 2: Declaring witnesses in TEI critical editions

6.3. Guide 3: Encoding a basic critical apparatus in TEI

Question: How can textual variation be represented explicitly rather than stored as a preformatted apparatus string?

Guide 3 introduces <app>, <lem>, <rdg>, and @wit, and connects readings with the witnesses declared in Guide 2. 

edited passage
     │
     â–¼
 <app>
   /   \
<lem> <rdg>
  │     │
  A     B

How to read this diagram. The apparatus entry is no longer a single formatted string. Its lemma, readings, and witness relationships are separate parts of the editorial record.

Stage reached. The TEI document contains a small structured, lemma-based apparatus.

Guide 3: Encoding a basic critical apparatus in TEI

6.4. Guide 4: Encoding complex textual variation in TEI

Question: What happens when textual variation is more complex than one lemma followed by one alternative word?

Guide 4 extends the basic model to common editorial phenomena such as omissions, additions, corrections, conjectures, uncertainty, grouped readings, transpositions, and readings of unequal extent.

Important distinction. Similar-looking absences or changes do not necessarily make the same editorial claim: an omission is not a deletion, uncertain text is not empty text, and a conjecture is not witness evidence.

Stage reached. The TEI source can preserve both textual alternatives and the editorial information needed to interpret more complex variation.

Guide 4: Encoding complex textual variation in TEI

6.5. Guide 5: Processing TEI critical apparatus data with Lua

Question: How can a growing collection of encoded relationships be processed consistently and checked before typesetting?

Guide 5 introduces Lua as an intermediate processing layer. It shows how apparatus data can be collected, normalized, references resolved, records validated, and diagnostics produced. It also distinguishes work that can be handled directly by ConTeXt XML setups from work for which Lua provides a clearer or more flexible solution. 

TEI editorial data
        │
        â–¼
      Lua
  ┌─────┼─────┐
  │     │     │
resolve check normalize
  │     │     │
  └─────┼─────┘
        â–¼
validated editorial records

How to read this diagram. Lua does not replace TEI or editorial judgement. It makes systematic operations on the encoded evidence explicit and inspectable before final composition.

Stage reached. The editorial meaning of the data is explicit enough for the typographical layer to take over.

Guide 5: Processing TEI critical apparatus data with Lua

6.6. Guide 6: Typesetting a TEI critical apparatus with ConTeXt

Question: How should validated editorial information become a readable scholarly page?

Guide 6 turns the encoded and processed information into typographical structures. It develops lemmas, readings, witness sigla, apparatus placement, line and passage references, multiple annotation layers, parallel texts, translations, and bibliographical notes. 

structured editorial data
          │
          â–¼
       ConTeXt
          │
    ┌─────┼─────┐
    │     │     │
  text apparatus notes
    │     │     │
    └─────┼─────┘
          â–¼
    scholarly page

How to read this diagram. ConTeXt does not establish the textual evidence. It gives the already established editorial relationships a controlled typographical form.

Stage reached. The workflow now reaches its reader-facing result: a critical edition whose documentary structure and typographical presentation remain distinct but coordinated.

Guide 6: Typesetting a TEI critical apparatus with ConTeXt

7. Choose your path

The guides form a progression, but you do not have to read every page before consulting the one that addresses your present problem.

If you want to… Begin with…
Understand why a critical apparatus is more than a specialised note system This orientation page
Understand an unfamiliar editorial, XML, TEI, Lua, or ConTeXt term Glossary of terms used in the TEI XML critical edition guides
Learn the basic structure of a TEI document Understanding TEI documents for critical editions
Declare manuscripts, printed editions, and other witnesses Declaring witnesses in TEI critical editions
Encode lemmas and variant readings Encoding a basic critical apparatus in TEI
Represent omissions, additions, corrections, conjectures, or grouped readings Encoding complex textual variation in TEI
Inspect, validate, sort, or transform TEI apparatus data Processing TEI critical apparatus data with Lua
Produce a typeset critical text and apparatus Typesetting a TEI critical apparatus with ConTeXt
Construct an apparatus directly in ConTeXt without using TEI XML Building a critical apparatus with ConTeXt

8. The architecture at a glance

The complete workflow can now be viewed as a set of cooperating layers: 

                  EDITORIAL JUDGEMENT
                         │
                         │ establishes
                         â–¼
                 TEXTUAL EVIDENCE
                         │
                         │ encoded as
                         â–¼
                      TEI XML
                         │
                 ┌───────┴────────┐
                 │                │
                 â–¼                â–¼
          ConTeXt XML          Lua
             setups         processing
                 │                │
                 └───────┬────────┘
                         â–¼
                      ConTeXt
                         │
                         │ composes
                         â–¼
                  SCHOLARLY PAGE
                         │
                         â–¼
                       READER

How to read this diagram. Editorial judgement establishes how the evidence is interpreted. TEI records that evidence and those relationships in structured form. ConTeXt XML setups and, where useful, Lua process the encoded information. ConTeXt then turns it into a page designed for human reading.

Guiding principle. The layers cooperate, but they should not be confused. A change in editorial judgement may require a change in the data; a change in page design should normally require only a change in the typographical layer.

9. Scope: what this collection does — and does not do

This collection is concerned with the construction of critical editions from TEI XML with ConTeXt, using Lua where it provides a useful processing layer.

Scope and limits. The collection does not attempt to provide:

  • a complete introduction to textual criticism;
  • a complete account of every part of the TEI Guidelines;
  • a universal encoding model suitable for every editorial tradition;
  • a replacement for a project-specific encoding policy;
  • a general course in XML;
  • a complete course in Lua programming;
  • a complete survey of all ConTeXt XML-processing facilities.

The guides introduce these subjects only where they are needed to solve a specific editorial or typographical problem.

Their examples are deliberately small enough to be understood and tested. They are intended to provide reusable principles rather than a rigid model that every edition must follow unchanged.

Building critical editions from TEI XML with ConTeXt

Glossary  ·  Start with: Guide 1  ·  Final guide: Guide 6  ·  ConTeXt-only route: Building a critical apparatus with ConTeXt

Related pages