Understanding TEI documents for critical editions

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

Guide 1 of 6 — Understanding TEI documents for critical editions

Collection overview  ·  Glossary  ·  Next: Declaring witnesses in TEI critical editions

A critical apparatus is not merely a sequence of notes placed beneath an edited text. It records a network of structured relationships: a lemma is associated with one or more readings; each reading is supported by one or more witnesses; some readings may be omitted, uncertain, corrected, conjectural, or grouped according to an editorial analysis.

These relationships can be represented typographically in a compact printed apparatus, but the printed form usually suppresses much of the underlying structure. Abbreviations, sigla, punctuation, and ordering conventions make the apparatus readable to specialists, yet they do not by themselves provide a reusable or machine-processable description of the evidence.

TEI XML is useful because it allows the edition to record these relationships explicitly. Witnesses can be declared once and referenced repeatedly; lemmas and readings can remain distinct; editorial responsibility and uncertainty can be encoded separately; and the same structured source can later support different forms of output, such as a positive apparatus, a negative apparatus, a witness report, a parallel text, or a critical edition typeset with ConTeXt.

The general principle is:

 
textual evidence 
↓ 
structured TEI encoding 
↓ 
selection and validation 
↓ 
typographical presentation 

The TEI document therefore does not merely contain the text of the edition. It also provides the documentary structure from which the apparatus can be inspected, checked, transformed, and typeset.

Because this structure is hierarchical, a critical edition encoded in TEI XML is built from nested elements and explicit references. Before introducing witnesses, lemmas, readings, or apparatus entries, it is therefore necessary to understand the document that will contain them.

This guide begins with an ordinary sentence:

The mind seeks unity.

It then shows how that sentence can become part of:

• a structured XML document;
• a TEI document;
• a source file that can later be enriched with critical data;
• a document that ConTeXt can load and process.

The progression followed here is:

plain textual content
        ↓
markup identifies structure
        ↓
XML supplies the general syntax
        ↓
TEI supplies a scholarly vocabulary
        ↓
the document becomes a structured source
        ↓
ConTeXt can process and typeset it

No previous knowledge of XML or TEI is required.

1. Where this guide fits in the collection

The six guides follow a progressive workflow:

[TEI DOCUMENT]                 ← Guide 1
      ↓
witness declarations
      ↓
basic apparatus entries
      ↓
complex textual variation
      ↓
Lua processing
      ↓
ConTeXt typesetting

This first guide establishes the container in which the later editorial data will be recorded.

It introduces:

• plain text and markup;
• XML elements and attributes;
• textual content;
• parent and child relationships;
• the XML document tree;
• the difference between XML and TEI;
• the main parts of a TEI document;
• XML identifiers and references;
• well-formedness;
• validation;
• a minimal TEI file suitable for later guides.

It does not yet explain:

• how witnesses are declared;
• how sigla are assigned;
• how <app>, <lem>, or <rdg> are used;
• how apparatus data are processed with Lua;
• how a complete critical apparatus is typeset.

Those subjects are introduced in the following guides.

2. From plain text to structured text

2.1. Plain text

Consider the sentence:

The mind seeks unity.

The characters are readable, but the sentence contains no explicit machine-readable description of its role.

A human reader may understand that it is:

• a sentence;
• part of a paragraph;
• part of a larger text;
• perhaps a quotation or an edited passage.

A computer receives only a sequence of characters unless those relationships are represented explicitly.

Conceptually, the unmarked text is flat:

T h e   m i n d   s e e k s   u n i t y .

Nothing in that character sequence states that the sentence belongs to a paragraph, a chapter, or a critical edition.

2.2. Adding structure

Markup surrounds or associates content with labels that describe its structure or function.

For example:

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

The opening tag:

<p>

marks the beginning of a paragraph.

The closing tag:

</p>

marks its end.

The textual content remains:

The mind seeks unity.

The markup adds structural information:

paragraph
└── The mind seeks unity.

2.3. Markup is not necessarily typography

The element name p identifies the content as a paragraph. It does not by itself specify:

• the typeface;
• the font size;
• the indentation;
• the line spacing;
• the space before or after the paragraph;
• the page on which the paragraph will appear.

Those decisions belong to the processing and typesetting system.

This distinction is central to the entire collection:

markup says what the content is
              ↓
typesetting determines how it appears

For example, the same XML paragraph could be rendered as:

• an indented paragraph in a printed book;
• a block of text on a web page;
• a line in a diplomatic transcription;
• a passage in a parallel-text layout;
• text read aloud by another application.

The underlying structural description does not have to change.

Guiding principle. XML and TEI describe the structure and meaning of the source; ConTeXt determines its typographical form. Keeping these responsibilities separate makes the same encoded text reusable in several outputs.

3. XML as a structural language

3.1. What XML is

XML stands for Extensible Markup Language.

XML provides a general syntax for representing structured information. It does not supply one fixed vocabulary for every kind of document.

An XML author may create elements appropriate to a particular domain:

<paragraph>...</paragraph>

<person>...</person>

<manuscript>...</manuscript>

<reading>...</reading>

These names can all be used in XML if the document follows XML syntax.

A community may then define a shared vocabulary and rules for using those elements. TEI is one such vocabulary.

The relationship can be summarised as follows:

Level	What it provides	Example
Plain text	Character content without explicit structure	The mind seeks unity.
XML	A syntax for marking, nesting, and linking structures	<p>The mind seeks unity.</p>
TEI	A scholarly vocabulary expressed in XML	<TEI>, <teiHeader>, <text>, <app>
ConTeXt	Processing and typographical presentation	Paragraphs, notes, apparatuses, lineation, and PDF output

3.2. Elements, attributes, and textual content

XML documents are constructed from a small number of recurring components.

3.2.1. Elements

An XML element normally consists of:

• a start tag;
• content;
• an end tag.

For example:

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

This can be analysed as:

Part	Example	Function
Start tag	<p>	Opens the element
Textual content	The mind seeks unity.	Supplies the content of the paragraph
End tag	</p>	Closes the element

The whole structure is the element:

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

The words between the tags are its textual content.

3.2.2. Start tags and end tags

The end tag repeats the element name with an initial slash:

<p> ... </p>

<title> ... </title>

<body> ... </body>

The start and end names must match.

This is correct:

<title>A small critical-edition example</title>

This is not correct:

<title>A small critical-edition example</heading>

3.2.3. Empty elements

Some XML elements contain no textual content or child elements.

They may be written with a self-closing tag:

<lb/>

This is equivalent in XML structure to:

<lb></lb>

The first form is more compact.

In TEI, an empty element such as <lb/> may mark a line boundary without containing the line itself.

Empty elements will be used only when they become necessary in later guides.

3.2.4. Attributes

An attribute adds information to an element.

It is written inside the start tag:

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

Here:

• p is the element name;
• xml:id is the attribute name;
• p1 is the attribute value.

The structure can be represented as:

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

Attribute values must be quoted:

xml:id="p1"

Single quotation marks are also permitted by XML:

xml:id='p1'

A project should normally adopt one style and use it consistently.

3.2.5. Elements and attributes perform different roles

The difference between an element and an attribute can be illustrated as follows:

Component	Typical role	Example
Element	Identifies or contains a structural part of the document	<p>...</p>
Attribute	Adds information about an element	xml:id="p1"
Textual content	Contains the characters represented by the element	The mind seeks unity.

The complete example is:

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

3.2.6. Markup and textual content

In the following example:

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

the markup is:

<p xml:id="p1">
</p>

The textual content is:

The mind seeks unity.

This distinction matters because the final reader may see only the textual content, while the processing system uses the markup to determine how that content should be handled.

3.3. Nested elements

An XML element may contain other elements.

For example:

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

The <body> element contains the <p> element.

The relationship can be represented as:

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

3.3.1. Parent and child elements

In this structure:

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

<body> is the parent of <p>.

<p> is a child of <body>.

The terms describe a direct relationship.

In a larger structure:

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

the relationships are:

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

Here:

• body is a child of text;
• p is a child of body;
• text is an ancestor of p;
• p is a descendant of text.

3.3.2. Sibling elements

Elements that share the same parent are siblings.

For example:

<body>
  <p>The mind seeks unity.</p>
  <p>Reason examines the conditions of knowledge.</p>
</body>

The two <p> elements are siblings:

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

Sibling order is significant. The first paragraph precedes the second in the document.

3.4. The XML document tree

Because XML elements are nested, the document can be understood as a tree.

Consider:

<text>
  <body>
    <p>The mind seeks unity.</p>
    <p>Reason examines knowledge.</p>
  </body>
</text>

The same structure can be displayed as:

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

The textual order and the hierarchical order are both represented.

This tree model allows a processor to ask questions such as:

• Which paragraphs belong to the body?
• What textual content belongs to the first paragraph?
• Which elements are children of <text>?
• Does a particular paragraph have an identifier?
• Which apparatus entries occur inside a paragraph?
• Which readings belong to one apparatus entry?

The later guides will use this structure to retrieve critical data.

4. From XML to TEI

4.1. XML and TEI are not the same thing

XML defines a general syntax.

It does not state that a textual edition should use:

• <TEI>;
• <teiHeader>;
• <text>;
• <body>;
• <app>;
• <lem>;
• <rdg>.

Those names belong to the TEI vocabulary.

An invented document such as this may be well-formed XML:

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

But it is not a TEI document.

The same general information can be represented with TEI elements:

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

The difference is not primarily visual. Both files use XML syntax.

The difference lies in the vocabulary, the agreed meaning of the elements, and the structural rules that govern how those elements may be combined.

In the invented XML document, names such as <edition>, <metadata>, and <paragraph> have only the meaning assigned to them by the author or project.

In a TEI document, elements such as <TEI>, <teiHeader>, <text>, and <p> belong to a documented scholarly vocabulary. Their functions and permitted relationships are defined by the TEI model and can therefore be understood and processed consistently by different users and applications.

A document is therefore not TEI merely because it uses XML syntax or TEI-like element names. It must use the TEI namespace and follow the selected TEI model.

Do not confuse syntax with vocabulary. A document may be perfectly well-formed XML without being a TEI document. TEI adds a defined scholarly vocabulary and structural expectations to XML syntax.

XML	TEI
Defines a general markup syntax	Defines a scholarly vocabulary expressed in XML
Allows element and attribute names to be created	Supplies defined elements and attributes
Requires correct XML structure	Adds TEI-specific structural and semantic expectations
Can represent many kinds of data	Is designed particularly for texts and textual scholarship

The relationship is:

XML
└── general syntax for structured documents
    └── TEI
        └── scholarly vocabulary for representing texts

4.2. The main structure of a TEI document

A minimal TEI document has two principal parts:

TEI
├── teiHeader
└── text

The <teiHeader> documents the encoded source.

The <text> contains the text being encoded.

A more developed view is:

TEI
├── teiHeader
│   └── fileDesc
│       ├── titleStmt
│       ├── publicationStmt
│       └── sourceDesc
└── text
    └── body
        └── p

Each of these structures has a distinct role.

4.3. The XML declaration

An XML document may begin with an XML declaration:

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

This line states:

Part	Meaning
version="1.0"	The document follows XML 1.0
encoding="UTF-8"	The file uses the UTF-8 character encoding

The XML declaration is not an XML element.

It has no closing tag and is not part of the TEI vocabulary.

Conceptually:

XML declaration
      ↓
TEI root element
      ├── teiHeader
      └── text

UTF-8 is appropriate for multilingual scholarly material because it can represent, among many other scripts:

• Latin characters;
• accented characters;
• Greek;
• Cyrillic;
• Hebrew;
• Arabic;
• many historical and specialist characters represented in Unicode.

The actual file must be saved using the encoding declared on this line.

4.4. The root <TEI> element

Every well-formed XML document has exactly one outermost element, called the root element.

In an individual TEI document, the root element is normally <TEI>:

<TEI xmlns="http://www.tei-c.org/ns/1.0">
  ...
</TEI>

Everything else in the document is contained, directly or indirectly, inside this element.

Correct:

<TEI xmlns="http://www.tei-c.org/ns/1.0">
  <teiHeader>...</teiHeader>
  <text>...</text>
</TEI>

Incorrect, because it has two top-level elements:

<teiHeader>...</teiHeader>
<text>...</text>

The correct structure is:

TEI
├── teiHeader
└── text

4.5. The TEI namespace

The root element in the examples contains this attribute:

xmlns="http://www.tei-c.org/ns/1.0"

The complete start tag is:

<TEI xmlns="http://www.tei-c.org/ns/1.0">

The xmlns declaration identifies the elements in the document as belonging to the TEI namespace.

Without the namespace declaration:

<TEI>
  ...
</TEI>

the element name may look like TEI to a human reader, but an XML processor does not automatically know that it belongs to the TEI vocabulary.

With the namespace declaration:

<TEI xmlns="http://www.tei-c.org/ns/1.0">
  ...
</TEI>

the unprefixed elements contained within it belong, by default, to the TEI namespace.

Conceptually:

element name:       p
namespace:          http://www.tei-c.org/ns/1.0
combined identity:  TEI paragraph element

The namespace address is an identifier. It should be copied exactly.

It is not necessary to visit that address while processing the document.

5. The TEI header and textual body

5.1. The <teiHeader>

The TEI header documents the encoded text and the file that contains it.

A minimal header used in this guide is:

<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 structure is:

teiHeader
└── fileDesc
    ├── titleStmt
    │   └── title
    ├── publicationStmt
    │   └── p
    └── sourceDesc
        └── p

5.1.1. The <fileDesc>

The <fileDesc> element contains the main bibliographical description of the TEI file.

In this minimal example, it contains three required divisions:

fileDesc
├── titleStmt
├── publicationStmt
└── sourceDesc

5.1.2. The <titleStmt>

The title statement identifies the work or encoded resource:

<titleStmt>
  <title>A small critical-edition example</title>
</titleStmt>

Larger projects may also record:

• authors;
• editors;
• translators;
• encoders;
• other contributors;
• statements of responsibility.

Those additions are not needed for the first example.

5.1.3. The <publicationStmt>

The publication statement describes the publication or availability of the encoded resource.

For this teaching file:

<publicationStmt>
  <p>Unpublished teaching example.</p>
</publicationStmt>

A published project may instead record a publisher, date, place, licence, or distribution information.

5.1.4. The <sourceDesc>

The source description identifies the source from which the electronic text was derived.

For this first artificial example:

<sourceDesc>
  <p>Created for the ConTeXt Garden TEI guides.</p>
</sourceDesc>

In a real critical edition, the source description may become much richer. It may identify:

• manuscripts;
• printed editions;
• archival sources;
• existing transcriptions;
• bibliographical descriptions;
• relations between sources.

The witness declarations introduced in Guide 2 belong to this broader documentary context.

5.2. The <text> element

The <text> element contains the encoded textual work:

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

At this stage, the text contains only one body and one paragraph.

Later it may contain:

• front matter;
• body matter;
• back matter;
• divisions;
• headings;
• paragraphs;
• quotations;
• verse;
• apparatus entries;
• other textual structures.

The present guide uses only what is needed for a first working file.

5.3. The <body> element

The <body> contains the main textual content:

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

The hierarchy is:

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

A larger body might contain several paragraphs:

<body>
  <p>The mind seeks unity.</p>
  <p>Reason examines the conditions of knowledge.</p>
</body>

or one or more textual divisions:

<body>
  <div>
    <head>First chapter</head>
    <p>The mind seeks unity.</p>
  </div>
</body>

Divisions and headings are not required for the first MWE.

6. Building the first TEI document

6.1. A first minimal TEI document

Create a plain-text file named:

tei-guide-01.xml

Insert the following content:

<?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 file is the source document used throughout the rest of the guide.

Its complete structure 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.

6.2. Reading the first document line by line

Source	Function
<?xml version="1.0" encoding="UTF-8"?>	Declares the XML version and character encoding
<TEI xmlns="http://www.tei-c.org/ns/1.0">	Opens the root TEI element and declares the TEI namespace
<teiHeader>	Opens the document header
<fileDesc>	Opens the principal file description
<titleStmt>	Opens the title and responsibility section
<title>...</title>	Records the title of the encoded resource
<publicationStmt>	Opens the publication statement
<sourceDesc>	Opens the source description
<text>	Opens the encoded textual work
<body>	Opens the main textual body
<p>...</p>	Records one paragraph
</TEI>	Closes the root element

The indentation is not what creates the hierarchy.

These two fragments represent the same XML structure:

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

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

The first form is preferable for human editing because the nesting is easier to see.

The hierarchy is determined by the tags, not by the visible indentation.

7. Identifiers and references

7.1. Adding identifiers

Editorial projects often need to refer to a particular element from another part of the document.

An identifier can be added with xml:id.

For example:

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

The structure is now:

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

The value p1 uniquely identifies this paragraph within the XML document.

7.2. Rules for xml:id values

For the purposes of these guides, use identifiers that:

• begin with a letter or underscore;
• contain no spaces;
• remain unique within the document;
• remain stable when possible;
• describe identity rather than typography.

Useful examples include:

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

Avoid identifiers such as:

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

The page number or visual appearance may change, while the identity of the encoded object should remain stable.

7.3. Identifier and visible label

An XML identifier is not necessarily a label intended for readers.

For example:

xml:id="ms-paris-123"

might identify a witness whose printed siglum is:

P

The functions are different:

XML identifier	Printed label or siglum
Used for linking within the encoded data	Used for communication with readers
Must follow XML identifier rules	May follow editorial and typographical conventions
Should remain stable in the source	May vary between forms of publication
Example: ms-paris-123	Example: P

This distinction becomes important in Guide 2.

7.4. References

A reference points from one encoded object to another.

Suppose the paragraph has this identifier:

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

Another element could refer to it using:

target="#p1"

The initial number sign indicates a reference to an identifier in the same document:

#p1
 ↓
find xml:id="p1"
 ↓
retrieve the identified paragraph

The general relation is:

declaration
<p xml:id="p1">...</p>

reference
<ptr target="#p1"/>

The second element points to the first.

This guide does not require the <ptr> element in the minimal document. The example only demonstrates how identifiers and references work together.

The critical apparatus will later use the same principle:

witness declaration
xml:id="A"
        ↑
        │
reading reference
wit="#A"

7.5. A second version with a paragraph identifier

The first file can now be extended slightly:

<?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>

The only change is:

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

This small addition prepares the document for later linking operations without yet introducing critical-apparatus structures.

8. Well-formedness, validation, and correctness

8.1. Well-formed XML

An XML document is well formed when it follows the fundamental syntactic rules of XML.

Well-formedness does not establish that the document is good TEI or that the editorial information is correct.

It establishes that an XML processor can construct a coherent document tree.

The most important rules for the present guide are:

• the document has exactly one root element;
• every opened element is closed;
• start and end tag names match;
• elements are properly nested;
• attribute values are quoted;
• identifiers are not duplicated;
• reserved characters are escaped where required.

8.2. One root element

Correct:

<TEI xmlns="http://www.tei-c.org/ns/1.0">
  <teiHeader>...</teiHeader>
  <text>...</text>
</TEI>

Incorrect:

<teiHeader>...</teiHeader>
<text>...</text>

The incorrect example contains two top-level elements.

A document must instead have one structure containing both:

TEI
├── teiHeader
└── text

8.3. Every start tag must be closed

Correct:

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

Incorrect:

<p>The mind seeks unity.

An empty element can close itself:

<lb/>

8.4. Start and end tag names must match

Correct:

<title>A small critical-edition example</title>

Incorrect:

<title>A small critical-edition example</head>

XML element names are also case-sensitive.

These are different names:

<TEI>
<tei>
<Tei>

A start tag and its end tag must use the same capitalization:

<TEI> ... </TEI>

8.5. Elements must be properly nested

Correct:

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

Incorrect:

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

The incorrect version crosses the element boundaries.

A useful rule is:

the last element opened
        ↓
must be the first element closed

Correct nesting behaves like nested containers:

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

The corresponding closing order is reversed:

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

8.6. Attribute values must be quoted

Correct:

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

Incorrect:

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

Correct with single quotation marks:

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

Consistent double quotation marks are used throughout these guides.

8.7. Reserved characters

Some characters have a structural meaning in XML.

For example, the less-than sign begins a tag:

<

If the character itself is required in textual content, it must normally be escaped:

<

Similarly, an ampersand in textual content is written:

&

For example:

<p>Reason & freedom</p>

This represents the textual content:

Reason & freedom

Common predefined XML entities include:

Entity	Character represented
&lt;	<
&gt;	>
&amp;	&
&quot;	Double quotation mark
&apos;	Apostrophe

Not every greater-than sign needs to be escaped in ordinary text, but escaping it as > can make paired examples clearer.

8.8. Well-formed is not the same as valid

Three different questions must be distinguished:

Is the XML syntactically coherent?
        ↓
Is it allowed by the chosen TEI schema?
        ↓
Is the encoded scholarship correct?

These correspond to three different levels:

Level	Question	Example of a possible problem
Well-formedness	Does the file obey XML syntax?	An unclosed <p> element
Validation	Does the file follow the selected TEI model or schema?	An element used in a context where the schema does not permit it
Editorial correctness	Does the file represent the textual evidence accurately?	A reading attributed to the wrong witness

A document can be well-formed XML without being valid TEI.

For example:

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

This may be well-formed XML:

• it has one root element;
• the elements are correctly opened and closed;
• the nesting is coherent.

But <banana> is not thereby an appropriate TEI element in this position.

A document can also be valid according to a schema while containing a false editorial claim.

For example, a structurally permitted witness reference may point to the wrong manuscript because of an editorial error.

Validation checks structure. It does not replace scholarship.

A valid file can still contain a false claim. XML well-formedness and TEI validation test formal structures; they cannot establish whether the encoded textual evidence is historically or philologically correct.

8.9. What validation does

Validation compares a document with a schema or another declared set of structural rules.

A schema may specify:

• which elements are permitted;
• where those elements may occur;
• which attributes are available;
• which values are allowed;
• which structures are required;
• how many times a structure may occur.

Project-specific checks may add further rules:

Every witness reference must resolve to a declaration.

Every xml:id value must be unique.

Every apparatus entry must contain the structures required by the project.

Every reading type must belong to the project’s controlled vocabulary.

Some of these checks may be performed by a TEI schema.

Others may be implemented later with Lua or specialised validation tools.

8.10. A compact diagnostic table

Problem	Well formed?	Necessarily valid TEI?
Missing closing tag	No	No
Two root elements	No	No
Unquoted attribute value	No	No
Correct XML containing an invented element	Yes	No
Correct TEI structure with a wrong witness attribution	Possibly	Possibly
Correct syntax, valid structure, and accurate editorial data	Yes	Yes, if checked against the intended schema

9. Saving and checking the TEI file

9.1. Saving the first TEI file

Save the document as:

tei-guide-01.xml

Use:

• a plain-text editor;
• UTF-8 encoding;
• the extension .xml;
• no word-processor formatting.

Suitable editors generally provide:

• visible indentation;
• XML syntax highlighting;
• matching-tag assistance;
• encoding information;
• error reporting.

The file should contain:

<?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>

At this point, the document contains no witnesses or apparatus entries.

That absence is intentional.

The file already establishes:

• a TEI root;
• a TEI namespace;
• a minimal header;
• a textual body;
• one identifiable paragraph;
• a stable base for the following guides.

9.2. Inspecting the file before using ConTeXt

Before processing the file, verify the following points.

Check	Expected result
File extension	.xml
Character encoding	UTF-8
Root element	One <TEI> element
Namespace	http://www.tei-c.org/ns/1.0
Header	One <teiHeader>
Text	One <text>
Main content	One <body>
Paragraph	One <p xml:id="p1">
Tag nesting	Every element closes before its parent closes
Identifier	p1 occurs only once as an xml:id

The expected tree is:

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

10. Loading the TEI file with ConTeXt

10.1. A minimal ConTeXt loading test

The detailed transformation of TEI into a critical edition belongs to Guide 6.

Nevertheless, it is useful to verify that ConTeXt can load the XML source and reach its textual content.

The complete XML source used by this test was saved in section 9.1 as tei-guide-01.xml.

Practical note. Save tei-guide-01.xml and tei-guide-01.tex in the same directory. The ConTeXt file loads the XML source directly with \xmlprocessfile.

Save the ConTeXt file as:

tei-guide-01.tex

Use this small ConTeXt test:

\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

Compile it with:

context tei-guide-01.tex

The intended visible result is:

The mind seeks unity.

The processing path is:

tei-guide-01.xml
        ↓
ConTeXt loads the XML tree
        ↓
the TEI header is ignored for this test
        ↓
the body is traversed
        ↓
the paragraph content is flushed
        ↓
The mind seeks unity.

This test is deliberately limited.

It does not yet:

• typeset the title stored in the TEI header;
• apply a complete document design;
• declare witnesses;
• process apparatus entries;
• use Lua to build editorial records.

Its purpose is only to verify the basic relation:

TEI source
    ↓
ConTeXt XML processing
    ↓
visible text

If the XML file cannot be loaded, first check:

• the filename;
• the directory;
• the XML nesting;
• matching start and end tags;
• quoted attribute values;
• the namespace;
• the UTF-8 encoding.

10.2. Source data and processing instructions remain separate

The example now consists of two files:

tei-guide-01.xml
└── textual and editorial source

tei-guide-01.tex
└── processing and typesetting instructions

This separation anticipates the architecture of the complete project:

File	Responsibility
XML file	Stores the structured textual and editorial information
ConTeXt file	Determines how the selected information is processed and presented

The sentence is stored in the XML source:

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

The paragraph formatting is controlled by ConTeXt:

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

A later typographical change does not require the sentence to be rewritten in the XML file.

Similarly, the later addition of witnesses and readings should enrich the structured source rather than embed the final printed apparatus directly in the text.

11. What this guide has established

The first guide has moved through the following stages:

plain text
    ↓
<p>The mind seeks unity.</p>
    ↓
XML elements, attributes, and hierarchy
    ↓
TEI root, header, and text
    ↓
a well-formed source file
    ↓
an identifiable paragraph
    ↓
a minimal ConTeXt loading test

The reader should now be able to distinguish:

Term	Meaning in this collection
Plain text	Character content without explicit structural markup
Markup	Labels and attributes identifying structure or function
XML	The general syntax used to construct the structured document
TEI	The scholarly vocabulary used within that XML syntax
Element	A structural unit such as <p>
Attribute	Additional information associated with an element
Textual content	The characters contained within an element
Root element	The single outermost element of the XML document
Namespace	The identifier associating element names with the TEI vocabulary
xml:id	A unique machine-readable identifier
Reference	A pointer to an identified object
Well-formed XML	XML that follows the fundamental syntax rules
Valid TEI	A document conforming to the selected TEI schema or model
Editorial correctness	Accurate representation of the textual evidence

The completed source currently has this structure:

TEI
├── teiHeader
│   └── file description
└── text
    └── body
        └── paragraph

The next guide will enrich the header with the sources on which a critical edition depends:

TEI
├── teiHeader
│   └── source description
│       └── witness declarations      ← Guide 2
└── text
    └── body
        └── paragraph

12. Next guide

The document now has a stable basic structure, but it does not yet identify the textual witnesses from which the edited text and its variants will be established.

The next guide explains:

• what counts as a witness;
• how witnesses are declared in TEI;
• how a machine-readable identifier differs from a printed siglum;
• how manuscripts and printed editions can be described;
• how readings will later refer to those declarations.

Next: Declaring witnesses in TEI critical editions

---

Guide 1 of 6 — Understanding TEI documents for critical editions

Collection overview  ·  Glossary  ·  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