Building critical editions from TEI XML

🚧 Documentation under construction : please feel free to modify this page and improve it.

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

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 this evidence should be represented. The resulting information must then be organised, verified, and presented to the reader in a usable form.

At first sight, this may appear to be mainly 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.

To understand why TEI XML becomes relevant, it is necessary to distinguish progressively between:

note
  → critical apparatus
    → structured editorial data
      → XML
        → TEI
          → Lua processing
            → ConTeXt typesetting

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:

• a comment;
• a reference;
• an explanation;
• a translation;
• a bibliographical indication;
• an editorial observation.

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:

• identify a lemma;
• delimit the extent of the passage concerned;
• list one or more variant readings;
• associate those readings with witnesses;
• distinguish corrections from original readings;
• identify omissions, additions, or transpositions;
• apply editorial conventions determined by the nature of the edition.

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

It is also how the textual evidence should be represented.

2. The apparatus as structured editorial information

Consider the compact apparatus entry:

mind] soul B

A reader familiar with critical editions may understand that:

• mind is the lemma printed in the edited text;
• soul is a variant reading;
• B is the witness that supports the variant.

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:

• lineation;
• note and apparatus placement;
• paragraph formatting;
• witness sigla;
• compact apparatus entries;
• multiple note series;
• parallel texts;
• the visual relationship between the edited text and its apparatus.

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:

• the scholarly description of the text and its variants;
• the typographical presentation of the resulting 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:

• produce a positive apparatus instead of a negative apparatus;
• suppress readings belonging to a particular class of witnesses;
• produce a reading text without an apparatus;
• create a diplomatic or synoptic presentation;
• generate an HTML edition;
• list every reading supported by one witness;
• detect references to witnesses that have not been declared;
• alter the order or typography of witness sigla;
• reuse the same data in another publication.

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:

• the textual content of the reading;
• the witness associated with that reading.

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:

• XML provides the general markup syntax;
• TEI provides the scholarly vocabulary and encoding model.

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:

• an apparatus entry;
• a lemma;
• one or more readings;
• references to the witnesses that support them.

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:

• <app> represents the apparatus entry;
• <lem> represents the lemma;
• <rdg> represents a variant reading;
• #ms-A, #ms-B, and #ed-C refer to witness declarations elsewhere in the TEI document.

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

• a diplomatic transcription;
• a reading text;
• a positive apparatus;
• a negative apparatus;
• a synoptic presentation;
• an HTML edition;
• a typeset PDF.

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

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 does 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:

• selected;
• checked;
• grouped;
• sorted;
• reformulated;
• converted into typographical structures.

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

It can be used to:

• inspect XML elements and attributes;
• resolve references to witnesses;
• collect readings belonging to an apparatus entry;
• apply a project-specific order to witness sigla;
• distinguish classes of readings;
• detect missing or inconsistent data;
• generate different forms of apparatus from the same source;
• pass the processed information to ConTeXt.

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 general workflow is therefore:

TEI XML source
      ↓
selection and transformation with Lua
      ↓
ConTeXt structures and commands
      ↓
typeset critical edition

Simple projects may require little or no explicit Lua code. More complex projects may use it extensively.

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:

• the typography of the edited text;
• the appearance of lemmas and readings;
• the form and order of witness sigla;
• the placement of apparatus entries;
• line and passage references;
• page breaking;
• several simultaneous apparatus layers;
• parallel original texts and translations;
• different output forms derived from the same source.

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.

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 page is an orientation page.

It explains why a critical apparatus may be represented as structured TEI XML data and how Lua and ConTeXt can then process and present that information. It does not attempt to provide a complete tutorial within a single page.

The collection contains three kinds of resource:

• this general orientation page;
• a glossary of editorial and technical terms;
• six guides that develop the workflow progressively.

Readers who are unfamiliar with the editorial or technical vocabulary should begin with 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 reference pages.

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

• Building a critical apparatus with ConTeXt

5.1. Glossary

The vocabulary used in this collection comes from several different fields.

Some terms belong to textual criticism and scholarly editing:

• apparatus;
• witness;
• siglum;
• lemma;
• reading;
• omission;
• conjecture;
• positive apparatus;
• negative apparatus.

Other terms describe XML structures:

• element;
• attribute;
• textual content;
• hierarchy;
• XML tree;
• identifier;
• reference;
• well-formed document;
• validation.

A third group belongs more specifically to TEI:

• TEI header;
• witness list;
• <app>;
• <lem>;
• <rdg>;
• @wit;
• xml:id.

The collection also uses terms connected with Lua and ConTeXt:

• Lua table;
• function;
• XML setup;
• selection;
• transformation;
• typesetting command.

The glossary is intended to be consulted while reading the guides. It does not merely define isolated words: it explains how each term is used within the TEI-to-ConTeXt workflow developed here.

Glossary: Glossary of terms used in the TEI XML critical edition guides

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.

Each guide concentrates on one stage of the process:

TEI document
    ↓
witness declarations
    ↓
basic apparatus entries
    ↓
complex textual variation
    ↓
Lua processing
    ↓
ConTeXt typesetting

6.1. Guide 1: Understanding TEI documents for critical editions

The first guide introduces the structure of a small TEI document suitable for experimentation.

It begins with the distinction between XML syntax and the TEI vocabulary. It then explains the main parts of a TEI document:

• the XML declaration;
• the root <TEI> element;
• the TEI header;
• the textual body;
• elements and attributes;
• textual content;
• XML identifiers and references;
• the hierarchical structure of the XML tree.

The guide does not yet attempt to encode a complete critical apparatus. Its purpose is to provide a small, understandable source document on which the later guides can build.

At the end of the guide, the reader will have a minimal TEI document, a small sample text, a basic header, and a source file that ConTeXt can load and inspect. No previous knowledge of TEI is required.

Guide 1: Understanding TEI documents for critical editions

6.2. Guide 2: Declaring witnesses in TEI critical editions

A critical apparatus repeatedly refers to manuscripts, printed editions, and other textual sources. Those sources must be identified before their readings can be cited consistently.

The second guide explains:

• what counts as a witness;
• how a siglum differs from an XML identifier;
• where witnesses are declared in a TEI document;
• how manuscripts and printed editions may be described;
• how witness descriptions are connected with apparatus readings;
• how several witnesses can be cited together;
• how groups or families of witnesses may be represented;
• how witness references are kept consistent with the declarations.

Particular attention is given to the distinction between a human-readable siglum such as A and a machine-readable reference such as #ms-A.

At the end of the guide, the reader will have a coherent TEI witness list and will be able to refer to its entries from elsewhere in the document.

Guide 2: Declaring witnesses in TEI critical editions

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

The third guide introduces the central TEI structures used to record textual variation.

It explains:

• the role of <app>;
• the distinction between <lem> and

 <rdg>;

• the use of @wit;
• how a reading is associated with one or more witnesses;
• how an apparatus entry is connected with the edited text;
• how several readings can belong to the same apparatus entry;
• how structured TEI data correspond to a compact printed apparatus.

The guide begins with short examples such as:

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

It then develops the same example sufficiently to show how the encoded structure can later be interpreted by ConTeXt.

At the end of the guide, the reader will have encoded a small lemma-based critical apparatus.

Guide 3: Encoding a basic critical apparatus in TEI

6.4. Guide 4: Encoding complex textual variation in TEI

Real critical editions contain cases that cannot be reduced to one lemma followed by one alternative word.

The fourth guide develops the basic apparatus model to represent more complex situations.

It covers:

• omissions;
• additions;
• substitutions;
• corrections;
• uncertain readings;
• editorial conjectures;
• orthographic variants;
• grouped readings;
• agreement between witnesses;
• transpositions;
• readings that concern passages of different extent;
• the distinction between positive and negative apparatus data.

The purpose is not to provide a universal encoding rule for every editorial tradition. Instead, the guide shows how the TEI model can be extended while keeping the scholarly relationships explicit.

It also explains why a project should define its own encoding policy before large quantities of material are entered.

At the end of the guide, the reader will have a broader model capable of representing common forms of textual variation without reducing them prematurely to a single printed notation.

Guide 4: Encoding complex textual variation in TEI

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

Once the apparatus has been encoded, the information must be extracted, checked, ordered, and prepared for typesetting.

The fifth guide introduces Lua as a processing layer between the TEI source and ConTeXt.

It explains how to:

• inspect the XML tree;
• retrieve elements and attributes;
• collect lemmas and readings;
• resolve witness references;
• store editorial information in Lua tables;
• apply a project-specific order to witness sigla;
• group readings according to editorial criteria;
• distinguish different types of apparatus entry;
• detect missing declarations and inconsistent references;
• prepare structured records for ConTeXt.

The guide does not attempt to teach Lua programming independently of the editorial problem. Each Lua mechanism is introduced because it performs a specific operation on the TEI data.

The examples also distinguish between tasks that can be performed directly by ConTeXt XML setups and tasks for which Lua provides a clearer or more flexible solution.

At the end of the guide, the reader will have a Lua representation of the TEI apparatus that can be checked, transformed, and passed to ConTeXt.

Guide 5: Processing TEI critical apparatus data with Lua

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

The sixth guide turns the encoded and processed information into a readable critical edition.

It explains how to:

• load the TEI source;
• typeset the edited text;
• connect passages in the text with apparatus entries;
• format lemmas, readings, and witness sigla;
• place the apparatus at the bottom of the page or elsewhere;
• manage line, paragraph, and passage references;
• compose compact apparatus paragraphs;
• connect TEI data with several ConTeXt apparatus layers;
• reuse TEI structures in parallel-text layouts where required;
• generate different apparatus forms from the same TEI source;
• separate editorial encoding from typographical configuration.

The guide also shows how the same underlying data may produce several outputs, for example:

• a reading text without an apparatus;
• a text with a negative apparatus;
• a text with a positive apparatus;
• a fuller editorial report;
• a differently formatted PDF edition.

At the end of the guide, the reader will have a complete experimental workflow:

TEI XML source
      ↓
Lua and ConTeXt processing
      ↓
edited text and critical apparatus
      ↓
typeset PDF

Guide 6: Typesetting a TEI critical apparatus with ConTeXt

7. Where should I begin?

The guides may be read in sequence, but readers can also enter the collection at the point corresponding to their immediate need.

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 collection as a layered workflow

The earlier table identified the principal responsibilities of textual scholarship, TEI XML, Lua, and ConTeXt. The same workflow can also be viewed more abstractly as four cooperating layers.

Layer	Central question	Typical contents
Editorial layer	What textual evidence exists, and how should it be interpreted?	Witnesses, readings, lemmas, omissions, corrections, conjectures
Encoding layer	How should the editorial information be recorded explicitly?	TEI elements, attributes, identifiers, and references
Processing layer	How should the encoded data be selected, checked, grouped, or transformed?	ConTeXt XML setups, Lua tables, functions, and processing rules
Typesetting layer	How should the resulting edition be presented to the reader?	Fonts, spacing, lineation, apparatus placement, page layout, and PDF output

These layers are connected, but they should not be confused.

For example:

• deciding that witness B contains a distinct reading belongs to the editorial layer;
• recording the reference wit="#ms-B" belongs to the encoding layer;
• sorting B according to the project’s witness order belongs to the processing layer;
• printing the siglum B in small capitals belongs to the typesetting layer.

This distinction makes the project easier to maintain because editorial changes do not need to be expressed as typographical changes, and typographical redesign does not require the scholarly data to be rewritten.

9. Scope and limits of the collection

This collection is concerned with the construction of critical editions from TEI XML using Lua and ConTeXt.

It 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

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