Encoding a basic critical apparatus in TEI

🚧 Documentation under construction — This page and its subpages are currently being revised. Contributions are welcome: feel free to correct, expand, and improve them.

Guide 3 of 6 — Encoding a basic critical apparatus in TEI

Previous: Declaring witnesses in TEI critical editions · Collection overview · Glossary · Next: Encoding complex textual variation in TEI

1 1. From declared witnesses to textual variation
2 2. Where this guide fits in the collection
3 3. From witness declarations to textual variation
4 4. The basic apparatus structure
5 5. Encoding inline apparatus entries
6 6. Encoded data and printed notation
- 6.1 6.1. TEI encoding and printed notation
- 6.2 6.2. Positive and negative information
7 7. Complete TEI MWE
8 8. Common encoding errors
9 9. Structural and editorial checks
10 10. Inspecting the basic apparatus with ConTeXt
11 11. A practical apparatus checklist
12 12. What this guide has established
13 13. Next guide
14 14. Related pages

1. From declared witnesses to textual variation

1.1. What the preceding guide established

The preceding guide declared the textual witnesses used by the edition.

The TEI document now knows that:

ms-A
    ↓
witness A

ms-B
    ↓
witness B

ed-C
    ↓
witness C

1.2. The next editorial task

The next task is to record how those witnesses differ.

Suppose that the three witnesses preserve these forms:

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

1.3. The two variable passages

The differences concern two passages:

mind / soul

seeks / desires

This guide explains how those relations can be encoded as structured TEI apparatus entries.

1.4. The progression followed in this guide

The progression is:

declared witnesses
        ↓
variable passage
        ↓
apparatus entry
        ↓
lemma and readings
        ↓
witness references
        ↓
possible printed apparatus

1.5. What the completed example will contain

At the end of the guide, the TEI source will contain:

the witness declarations created in Guide 2;
two inline apparatus entries;
one lemma in each entry;
one variant reading in each entry;
explicit witness references;
enough information to generate a simple lemma-based apparatus.

Guiding principle. TEI records the relation between readings and witnesses. It should not store the punctuation, abbreviations, or visual compression of one particular printed apparatus.

Reading the examples. Each major construction is divided into short steps: editorial evidence, TEI encoding, XML tree, edited text, and possible apparatus output. The frequent subsection headings make each code block easier to locate, discuss, and revise independently.

2. Where this guide fits in the collection

The six-guide workflow is:

TEI document
      ↓
witness declarations
      ↓
[BASIC APPARATUS ENTRIES]     ← Guide 3
      ↓
complex textual variation
      ↓
Lua processing
      ↓
ConTeXt typesetting

Guide 1 established the basic TEI document.

Guide 2 declared the witnesses.

This guide introduces:

textual variation;
apparatus entries;
lemmas;
variant readings;
witness support;
inline apparatus encoding;
several readings in one entry;
several witnesses supporting one reading;
the distinction between encoded data and printed notation;
a small ConTeXt inspection test.

This guide does not yet develop:

omissions;
additions;
corrections;
conjectures;
transpositions;
uncertain readings;
reading groups;
overlapping passages;
full reference resolution with Lua;
final apparatus typography.

Those subjects belong to Guides 4, 5, and 6.

3. From witness declarations to textual variation

3.1. The witness registry

The witness list created in Guide 2 identifies the sources:

<listWit>
  <witness xml:id="ms-A" n="A">
    The principal manuscript.
  </witness>

  <witness xml:id="ms-B" n="B">
    A later manuscript containing several alternative readings.
  </witness>

  <witness xml:id="ed-C" n="C">
    An early printed edition.
  </witness>
</listWit>

3.2. What witness declarations do and do not say

The declarations answer:

Which witnesses exist?

They do not yet answer:

What does each witness read at a particular location?

From inventory to relation. The witness list identifies the documentary sources; apparatus entries describe how those sources agree or differ at particular locations.

That second question is answered by the apparatus entries.

3.3. From witness identity to textual relation

The relation is:

witness registry
      ↓
declared identities
      ↓
apparatus entries refer to those identities
      ↓
readings are associated with witnesses

4. The basic apparatus structure

4.1. What an apparatus entry represents

An apparatus entry records one location of textual variation.

For example:

A C  mind
B    soul

The editorial relation can be expanded as:

apparatus entry
├── edited reading: mind
│   ├── supported by A
│   └── supported by C
└── alternative reading: soul
    └── supported by B

A compact printed apparatus might show:

mind] soul B

A positive apparatus might show:

mind A C] soul B

Both forms can be generated from the same structured relation.

The TEI encoding is:

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

The principal correspondence is:

Editorial concept	TEI representation	Example
Apparatus entry	`<app>`	One location containing textual variation
Lemma	`<lem>`	`mind`
Variant reading	`<rdg>`	`soul`
Witness support	`@wit`	`#ms-A #ed-C`
Possible printed form	Generated during processing	`mind] soul B`

4.2. The `<app>` element

The TEI element <app> represents one apparatus entry.

A minimal entry is:

<app>
  <lem>mind</lem>
  <rdg>soul</rdg>
</app>

Its tree is:

app
├── lem
│   └── mind
└── rdg
    └── soul

The <app> element groups the textual forms that belong to the same location.

It states that:

mind
and
soul

are not unrelated words elsewhere in the document.

They are competing textual forms within one apparatus entry.

The element does not itself determine:

which reading appears in the edited text;
which witnesses support each reading;
how the apparatus is printed;
where the printed apparatus is placed;
which punctuation separates its parts.

Those functions belong to its child elements, attributes, processing rules, and ConTeXt presentation.

4.3. The `<lem>` element

The TEI element <lem> represents the lemma.

In the examples used here, the lemma is the reading that appears in the edited text:

<lem>mind</lem>

The printed edited text contains:

The mind seeks unity.

The apparatus may refer back to that passage as:

mind]

The relation is:

edited text
    ↓
mind

TEI apparatus
    ↓
<lem>mind</lem>

printed apparatus
    ↓
mind]

A lemma may contain:

part of a word;
one word;
several words;
a line;
a longer passage.

This guide uses one-word lemmas so that the basic structure remains visible.

4.4. The `<rdg>` element

The TEI element <rdg> represents a reading.

In this example:

<rdg>soul</rdg>

the reading soul differs from the lemma mind.

The relation is:

lemma
└── mind

variant reading
└── soul

An apparatus entry may contain one or several <rdg> elements:

<app>
  <lem>mind</lem>
  <rdg>soul</rdg>
  <rdg>understanding</rdg>
</app>

The corresponding structure is:

app
├── lem
│   └── mind
├── rdg
│   └── soul
└── rdg
    └── understanding

Each reading remains a separate encoded object.

4.5. The `@wit` attribute

The attribute @wit identifies the witnesses supporting a lemma or reading.

For example:

<lem wit="#ms-A #ed-C">mind</lem>

states that the lemma mind is supported by:

#ms-A
#ed-C

The reading:

<rdg wit="#ms-B">soul</rdg>

is supported by:

#ms-B

The declarations from Guide 2 provide the targets:

xml:id="ms-A"    →    siglum A
xml:id="ms-B"    →    siglum B
xml:id="ed-C"    →    siglum C

The references resolve conceptually as:

wit="#ms-A #ed-C"
        ↓
split the attribute value
        ↓
#ms-A
#ed-C
        ↓
find the witness declarations
        ↓
retrieve A and C

and:

wit="#ms-B"
        ↓
find xml:id="ms-B"
        ↓
retrieve B

4.6. One witness and several witnesses

A single witness reference is written as:

wit="#ms-B"

Several references are separated by spaces:

wit="#ms-A #ed-C"

The attribute contains one value, but that value contains several references:

attribute:
    wit="#ms-A #ed-C"

references:
    #ms-A
    #ed-C

Do not separate the references with commas:

wit="#ms-A, #ed-C"

Do not repeat the attribute:

wit="#ms-A" wit="#ed-C"

Use one space-separated list:

wit="#ms-A #ed-C"

Reference syntax matters. The identifiers themselves do not contain the number sign. Write xml:id="ms-A" in the declaration, but #ms-A when referring to it from @wit.

5. Encoding inline apparatus entries

5.1. Encoding the first variant

The first textual difference is:

A  mind
B  soul
C  mind

The edited text adopts mind.

The relation is:

mind
├── A
└── C

soul
└── B

The TEI entry is:

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

Read line by line:

Source fragment	Meaning
`<app>`	Opens one apparatus entry
`<lem>`	Opens the lemma
`wit="#ms-A #ed-C"`	States that A and C support the lemma
`mind`	Supplies the lemma text
`<rdg>`	Opens one variant reading
`wit="#ms-B"`	States that B supports the reading
`soul`	Supplies the variant text
`</app>`	Closes the apparatus entry

5.2. Reading the first apparatus entry as a tree

The complete tree is:

app
├── lem
│   ├── wit
│   │   ├── #ms-A
│   │   └── #ed-C
│   └── text: mind
└── rdg
    ├── wit
    │   └── #ms-B
    └── text: soul

At the editorial level:

apparatus entry
├── adopted reading: mind
│   ├── witness A
│   └── witness C
└── alternative reading: soul
    └── witness B

At the printed level, one possible result is:

mind] soul B

The TEI tree is richer than the printed notation.

5.3. Inline apparatus

In an inline apparatus, the <app> element occurs directly at the location of the variation in the text.

The paragraph becomes:

<p xml:id="p1">
  The
  <app>
    <lem wit="#ms-A #ed-C">mind</lem>
    <rdg wit="#ms-B">soul</rdg>
  </app>
  seeks unity.
</p>

The tree contains both textual content and child elements:

p
├── text: The
├── app
│   ├── lem
│   │   └── mind
│   └── rdg
│       └── soul
└── text: seeks unity.

The <app> occupies the position of the variable passage.

A processor producing the edited text selects the lemma:

The
  ↓
mind
  ↓
seeks unity.

The resulting sentence is:

The mind seeks unity.

A different output could select witness B’s reading:

The soul seeks unity.

The encoded structure therefore contains more than one possible textual realisation.

5.4. Markup boundaries and spaces

Mixed textual content requires attention to spaces.

This compact encoding is clear:

<p xml:id="p1">The <app><lem wit="#ms-A #ed-C">mind</lem><rdg
wit="#ms-B">soul</rdg></app> seeks unity.</p>

For readability, the same structure may be indented:

<p xml:id="p1">
  The
  <app>
    <lem wit="#ms-A #ed-C">mind</lem>
    <rdg wit="#ms-B">soul</rdg>
  </app>
  seeks unity.
</p>

Indentation inside mixed-content elements can create whitespace text nodes. The exact effect depends on processing.

For the MWE used in this guide, the inline paragraph will therefore be written compactly:

<p xml:id="p1">The <app><lem wit="#ms-A #ed-C">mind</lem><rdg
wit="#ms-B">soul</rdg></app> <app><lem wit="#ms-A #ms-B">seeks</lem><rdg
wit="#ed-C">desires</rdg></app> unity.</p>

The line breaks occur inside tags or between complete structures rather than inside the ordinary textual phrases.

5.5. Adding the second apparatus entry

5.5.1. The second variation

The second variation is:

A  seeks
B  seeks
C  desires

5.5.2. The editorial relation

The relation is:

seeks
├── A
└── B

desires
└── C

5.5.3. Encoding the second apparatus entry

The second apparatus entry is encoded as follows:

<app>
  <lem wit="#ms-A #ms-B">seeks</lem>
  <rdg wit="#ed-C">desires</rdg>
</app>

5.5.4. Combining both apparatus entries

The complete paragraph now contains two apparatus entries:

<p xml:id="p1">The <app><lem wit="#ms-A #ed-C">mind</lem><rdg
wit="#ms-B">soul</rdg></app> <app><lem wit="#ms-A #ms-B">seeks</lem><rdg
wit="#ed-C">desires</rdg></app> unity.</p>

For structural inspection, the same paragraph may be displayed in an indented form:

<p xml:id="p1">
  The
  <app>
    <lem wit="#ms-A #ed-C">mind</lem>
    <rdg wit="#ms-B">soul</rdg>
  </app>
  <app>
    <lem wit="#ms-A #ms-B">seeks</lem>
    <rdg wit="#ed-C">desires</rdg>
  </app>
  unity.
</p>

The indentation is used here only to make the structure visible. In genuine mixed-content processing, whitespace must still be handled carefully.

5.5.5. Reading the resulting XML tree

The resulting XML tree can be represented as follows:

p
├── text: The
├── app
│   ├── lem: mind
│   └── rdg: soul
├── app
│   ├── lem: seeks
│   └── rdg: desires
└── text: unity.

Each <app> element occupies a distinct position in the paragraph. Its <lem> supplies the reading printed in the edited text, while its <rdg> records an alternative reading transmitted by another witness.

5.5.6. The edited text

The edited text reads:

The mind seeks unity.

5.5.7. A possible printed apparatus

A corresponding critical apparatus could be rendered as:

mind] soul B
seeks] desires C

The sequence is therefore:

TEI structure
      ↓
edited text
      ↓
critical apparatus

5.6. Several readings in one apparatus entry

An apparatus entry may contain more than one alternative reading.

Suppose that the witnesses read:

A  mind
B  soul
C  understanding

The TEI encoding is:

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

The tree is:

app
├── lem
│   ├── text: mind
│   └── witness: A
├── rdg
│   ├── text: soul
│   └── witness: B
└── rdg
    ├── text: understanding
    └── witness: C

A possible printed result is:

mind] soul B; understanding C

The semicolon belongs to the rendering.

It is not stored as part of either reading.

5.7. Several witnesses supporting one reading

Suppose that four witnesses exist:

A  mind
B  soul
C  mind
D  soul

The grouped support is:

mind
├── A
└── C

soul
├── B
└── D

The TEI entry is:

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

The reading is encoded once:

soul

Its witness support is expressed as a list:

#ms-B #ms-D

It should not be duplicated as two identical reading elements merely because two witnesses support it:

<rdg wit="#ms-B">soul</rdg>
<rdg wit="#ms-D">soul</rdg>

unless the project has a specific reason to preserve those readings as distinct records.

For ordinary shared support, one reading with several references is clearer:

<rdg wit="#ms-B #ms-D">soul</rdg>

6. Encoded data and printed notation

6.1. TEI encoding and printed notation

The TEI source and the printed apparatus perform different tasks.

TEI records:

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

A negative apparatus may print:

mind] soul B

A positive apparatus may print:

mind A C] soul B

A prose report may print:

Witness B reads “soul”, while A and C read “mind”.

A reading edition may print no apparatus entry at all.

The relation is:

one structured apparatus entry
        ↓
several possible renderings
        ├── negative apparatus
        ├── positive apparatus
        ├── prose report
        └── no visible apparatus

TEI source	Printed apparatus
Records elements and attributes	Uses typography and punctuation
Identifies all encoded witness support	May omit support that can be inferred
Preserves separate readings	Compresses them into one apparatus entry
Remains reusable	Is designed for one output

6.2. Positive and negative information

The TEI example explicitly records support for both the lemma and the alternative reading:

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

This is positive encoded information:

mind is supported by A and C
soul is supported by B

A printed negative apparatus may suppress the lemma support:

mind] soul B

The reader infers that the other relevant witnesses support the lemma.

The distinction is:

Encoded information	Printed selection
Lemma support: A C	May be omitted in a negative apparatus
Variant support: B	Printed explicitly
Complete structured relation	Compact editorial notation

The TEI source need not imitate the omissions of the printed notation.

It can preserve explicit information from which several apparatus forms are generated.

One source, several outputs. A complete TEI apparatus entry can support a negative apparatus, a positive apparatus, a prose report, or a reading text without apparatus. The source remains reusable because it records structure rather than one finished display.

7. Complete TEI MWE

7.1. File name

Save the following document as:

tei-guide-03.xml

7.2. Complete XML source

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

<TEI xmlns="http://www.tei-c.org/ns/1.0">
  <teiHeader>
    <fileDesc>
      <titleStmt>
        <title>A basic TEI critical apparatus</title>
      </titleStmt>

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

      <sourceDesc>
        <listWit>
          <witness xml:id="ms-A" n="A">
            The principal manuscript.
          </witness>

          <witness xml:id="ms-B" n="B">
            A later manuscript containing several alternative readings.
          </witness>

          <witness xml:id="ed-C" n="C">
            An early printed edition.
          </witness>
        </listWit>
      </sourceDesc>
    </fileDesc>
  </teiHeader>

  <text>
    <body>
      <p xml:id="p1">The <app><lem wit="#ms-A #ed-C">mind</lem><rdg
      wit="#ms-B">soul</rdg></app> <app><lem
      wit="#ms-A #ms-B">seeks</lem><rdg
      wit="#ed-C">desires</rdg></app> unity.</p>
    </body>
  </text>
</TEI>

7.3. What the complete document contains

The document now contains:

three declared witnesses;
one paragraph;
two inline apparatus entries;
two lemmas;
two variant readings;
explicit witness support for every lemma and reading.

7.4. Reading the complete TEI document as a tree

TEI
├── teiHeader
│   └── fileDesc
│       ├── titleStmt
│       │   └── title
│       ├── publicationStmt
│       │   └── p
│       └── sourceDesc
│           └── listWit
│               ├── witness A
│               ├── witness B
│               └── witness C
└── text
    └── body
        └── p [xml:id="p1"]
            ├── text: The
            ├── app
            │   ├── lem
            │   │   ├── text: mind
            │   │   └── wit: #ms-A #ed-C
            │   └── rdg
            │       ├── text: soul
            │       └── wit: #ms-B
            ├── app
            │   ├── lem
            │   │   ├── text: seeks
            │   │   └── wit: #ms-A #ms-B
            │   └── rdg
            │       ├── text: desires
            │       └── wit: #ed-C
            └── text: unity.

The two textual relations are:

entry 1
├── mind: A C
└── soul: B

entry 2
├── seeks: A B
└── desires: C

7.5. From the TEI source to witness texts

The same apparatus data imply three witness texts.

7.5.1. Witness A

Select the reading supported by #ms-A:

The mind seeks unity.

7.5.2. Witness B

Select the reading supported by #ms-B:

The soul seeks unity.

7.5.3. Witness C

Select the reading supported by #ed-C:

The mind desires unity.

Conceptually:

TEI apparatus data
        ↓
select witness A
        └── The mind seeks unity.

TEI apparatus data
        ↓
select witness B
        └── The soul seeks unity.

TEI apparatus data
        ↓
select witness C
        └── The mind desires unity.

This reconstruction illustrates why structured witness references are more powerful than a preformatted apparatus string.

8. Common encoding errors

8.1. Placing the witness siglum directly in the reading text

Incorrect:

<rdg>soul B</rdg>

This mixes:

the reading text;
its witness support;
its possible printed presentation.

Correct:

<rdg wit="#ms-B">soul</rdg>

The separation is:

reading text:       soul
witness reference:  #ms-B
printed siglum:     B

8.2. Referring to an undeclared witness

Incorrect:

<rdg wit="#ms-D">soul</rdg>

when no declaration contains:

xml:id="ms-D"

The reference has no target.

Correct either by using an existing witness:

<rdg wit="#ms-B">soul</rdg>

or by declaring the new witness before referring to it.

8.3. Adding the number sign to `xml:id`

Incorrect declaration:

<witness xml:id="#ms-A" n="A">
  The principal manuscript.
</witness>

Correct declaration:

<witness xml:id="ms-A" n="A">
  The principal manuscript.
</witness>

Correct reference:

wit="#ms-A"

The relation is:

declaration:  xml:id="ms-A"
reference:    #ms-A

8.4. Using commas inside `@wit`

Incorrect:

<lem wit="#ms-A, #ed-C">mind</lem>

Correct:

<lem wit="#ms-A #ed-C">mind</lem>

8.5. Repeating `@wit`

Incorrect:

<lem wit="#ms-A" wit="#ed-C">mind</lem>

An XML element cannot contain the same attribute twice.

Correct:

<lem wit="#ms-A #ed-C">mind</lem>

8.6. Leaving the reading outside the apparatus entry

Incorrect:

<app>
  <lem wit="#ms-A #ed-C">mind</lem>
</app>

<rdg wit="#ms-B">soul</rdg>

The reading is no longer grouped with the lemma.

Correct:

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

8.7. Storing the lemma separator in the TEI source

Avoid:

<lem wit="#ms-A #ed-C">mind]</lem>

The bracket belongs to the printed apparatus convention, not to the lemma.

Prefer:

<lem wit="#ms-A #ed-C">mind</lem>

ConTeXt can later add:

during rendering.

8.8. Encoding a preformatted apparatus string

Avoid storing:

<app>mind] soul B</app>

This does not identify:

the lemma;
the reading;
the witness;
the relation between them.

Use:

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

9. Structural and editorial checks

9.1. Structural checks

A basic apparatus entry should satisfy several rules.

Check	Expected result
Apparatus grouping	Every lemma and its readings belong to one `<app>`
Lemma	The entry contains one lemma in the model used by this guide
Reading	The entry contains at least one alternative reading
Witness references	Every `@wit` value points to declared witnesses
Reference syntax	Several references are separated by spaces
Reading text	Witness sigla are not embedded in the textual content
Typographical punctuation	Lemma separators and reading separators are not stored as reading text
XML structure	All elements are properly nested and closed

9.2. Editorial correctness

A structurally correct entry may still contain an editorial error.

For example:

<rdg wit="#ms-B">soul</rdg>

may be valid TEI but inaccurate if witness B actually reads mind.

9.3. Three levels of verification

Three levels remain distinct:

Level	Question
Well-formed XML	Are the tags and attributes syntactically correct?
Valid TEI	Is the apparatus structure permitted by the selected TEI model?
Editorial correctness	Does the entry represent the witnesses accurately?

Validation has limits. A file can be well-formed XML and valid TEI while still assigning the wrong reading to a witness. Technical validation cannot replace editorial verification.

10. Inspecting the basic apparatus with ConTeXt

10.1. Purpose of the inspection test

The final construction of a compact critical apparatus belongs to Guide 6.

The purpose of this small ConTeXt test is more limited. It verifies that ConTeXt can:

load the TEI document;
ignore the TEI header;
print each lemma in the edited text;
place the corresponding variant reading in a footnote;
retrieve and display the raw witness reference stored in

 @wit.

10.2. Why the raw witness identifier is retained

At this stage, the raw XML reference is deliberately retained:

#ms-B

The conversion of this identifier into the display siglum:

will be treated systematically in Guide 5.

Practical note. Save tei-guide-03.xml and tei-guide-03.tex in the same directory. This allows \xmlprocessfile to locate the XML source without an additional path.

10.3. ConTeXt source file

Save the ConTeXt file as:

tei-guide-03.tex

\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}

  \xmlsetsetup
    {#1}
    {tei:app}
    {xml:tei:apparatus}

  \xmlsetsetup
    {#1}
    {tei:lem}
    {xml:tei:lemma}

  \xmlsetsetup
    {#1}
    {tei:rdg}
    {xml:tei:reading}
\stopxmlsetups

\xmlregistersetup{xml:tei:document}

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

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

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

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

\startxmlsetups xml:tei:reading
  \xmlflush{#1}
  \space
  \ttx{\xmlatt{#1}{wit}}
\stopxmlsetups

\startxmlsetups xml:tei:apparatus
  \xmlfirst{#1}{tei:lem}
  \footnote
    {\xmlfirst{#1}{tei:lem}]
     \space
     \xmlall{#1}{tei:rdg}}
\stopxmlsetups

\starttext

\subject{Basic TEI apparatus}

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

\stoptext

10.4. Compilation

Compile with:

context tei-guide-03.tex

This MWE was tested successfully with ConTeXt LMTX.

10.5. Expected output

The edited text is:

Basic TEI apparatus

The mind¹ seeks² unity.

The corresponding footnotes contain:

1. mind] soul #ms-B
2. seeks] desires #ed-C

Output produced by the ConTeXt LMTX MWE for a basic TEI critical apparatus.

10.6. Processing path

The processing path is:

tei-guide-03.xml
        ↓
ConTeXt loads the TEI tree
        ↓
the TEI header is ignored
        ↓
the paragraph is processed
        ↓
each <app> selects its <lem>
        ↓
the lemma is printed in the edited text
        ↓
each <rdg> is placed in a footnote
        ↓
the raw @wit reference is displayed

10.7. Deliberate limitations of the test

This deliberately limited inspection test does not yet:

resolve #ms-B to B;
sort several witnesses;
generate a continuous apparatus paragraph;
produce positive and negative apparatus variants;
manage apparatus location labels;
apply final siglum typography;
handle omissions or more complex readings.

Its purpose is to verify the basic path:

TEI apparatus entry
        ↓
lemma in the edited text
        ↓
variant reading in a footnote
        ↓
raw witness reference displayed

10.8. A simpler fallback inspection test

If the previous setup requires adaptation to the ConTeXt version being used, the apparatus can first be inspected without notes.

Replace the apparatus setup with:

\startxmlsetups xml:tei:apparatus
  \bgroup
  [
  \xmlfirst{#1}{tei:lem}
  \space
  :
  \space
  \xmlall{#1}{tei:rdg}
  ]
  \egroup
\stopxmlsetups

The paragraph will then display an inspection form similar to:

The [mind : soul #ms-B] [seeks : desires #ed-C] unity.

This is not intended as final typography.

It makes the encoded structure visible while testing the XML selectors.

10.9. The role of each ConTeXt setup

Setup	Function
`xml:tei:document`	Associates TEI elements with processing setups
`xml:tei:flush`	Continues processing child content
`xml:tei:ignore`	Suppresses the TEI header from the visible output
`xml:tei:paragraph`	Typesets a TEI paragraph
`xml:tei:apparatus`	Selects the lemma and creates the note
`xml:tei:lemma`	Flushes the lemma text
`xml:tei:reading`	Flushes a reading and displays its witness reference

The ConTeXt test separates:

source structures
        ↓
selection rules
        ↓
typographical output

10.10. Source data and presentation remain separate

The TEI source stores:

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

The ConTeXt setup decides:

that the lemma is printed in the text;
that the reading appears in a note;
that a closing bracket separates lemma and reading;
that the witness reference is shown in typewriter style.

TEI XML	ConTeXt
Stores the apparatus entry	Selects and processes the entry
Stores the lemma	Prints the lemma in the edited text
Stores the readings	Places them in notes
Stores witness references	Determines how references are displayed
Does not store the lemma separator	Adds the closing bracket

A later change from footnotes to a compact apparatus paragraph does not require the TEI entries to be rewritten.

11. A practical apparatus checklist

Before moving to Guide 4, verify the following.

Check	Expected result
Witness declarations	A, B, and C remain declared in `<listWit>`
Paragraph	One paragraph contains two inline apparatus entries
First lemma	`mind`
First variant	`soul`
Second lemma	`seeks`
Second variant	`desires`
Lemma support	`mind`: A C; `seeks`: A B
Variant support	`soul`: B; `desires`: C
References	Every `@wit` value resolves to a declared witness
Reading content	No witness siglum or apparatus punctuation is embedded in the readings
Edited text	The lemmas produce “The mind seeks unity.”
ConTeXt inspection	The lemmas and readings can be reached from the XML tree

The expected apparatus tree is:

paragraph
├── text: The
├── apparatus entry 1
│   ├── lemma: mind
│   │   └── witnesses: A C
│   └── reading: soul
│       └── witness: B
├── apparatus entry 2
│   ├── lemma: seeks
│   │   └── witnesses: A B
│   └── reading: desires
│       └── witness: C
└── text: unity.

12. What this guide has established

12.1. The completed progression

This guide has moved from declared witnesses to structured records of textual variation:

witness declarations
        ↓
apparatus locations
        ↓
<app>
        ├── <lem>
        └── <rdg>
        ↓
@wit references
        ↓
reusable editorial data

12.2. The essential distinction

The essential distinction is between encoded evidence and printed notation. TEI records lemmas, readings, and witness support as separate objects. ConTeXt may later compress those objects into a negative apparatus, expand them into a positive apparatus, or use them to reconstruct the text of a selected witness.

12.3. Skills acquired

The reader should now be able to:

group a lemma and its readings inside one <app>;
associate each textual form with declared witnesses through @wit;
encode several readings or several supporting witnesses without duplication;
place apparatus entries directly at the locations of variation;
keep textual data separate from sigla, separators, and other output conventions.

13. Next guide

The model developed here handles straightforward substitutions. Guide 4 extends it to omissions, additions, corrections, conjectures, uncertainty, grouped readings, transposed order, and variants of unequal extent.

Guide 3 of 6 — Encoding a basic critical apparatus in TEI

Previous: Declaring witnesses in TEI critical editions · Collection overview · Glossary · Next: Encoding complex textual variation in TEI

14. Related pages

Encoding a basic critical apparatus in TEI

Contents

1. From declared witnesses to textual variation

1.1. What the preceding guide established

1.2. The next editorial task

1.3. The two variable passages

1.4. The progression followed in this guide

1.5. What the completed example will contain

2. Where this guide fits in the collection

3. From witness declarations to textual variation

3.1. The witness registry

3.2. What witness declarations do and do not say

3.3. From witness identity to textual relation

4. The basic apparatus structure

4.1. What an apparatus entry represents

4.2. The <app> element

4.3. The <lem> element

4.4. The <rdg> element

4.5. The @wit attribute

4.6. One witness and several witnesses

5. Encoding inline apparatus entries

5.1. Encoding the first variant

5.2. Reading the first apparatus entry as a tree

5.3. Inline apparatus

5.4. Markup boundaries and spaces

5.5. Adding the second apparatus entry

5.5.1. The second variation

5.5.2. The editorial relation

5.5.3. Encoding the second apparatus entry

5.5.4. Combining both apparatus entries

5.5.5. Reading the resulting XML tree

5.5.6. The edited text

5.5.7. A possible printed apparatus

5.6. Several readings in one apparatus entry

5.7. Several witnesses supporting one reading

6. Encoded data and printed notation

6.1. TEI encoding and printed notation

6.2. Positive and negative information

7. Complete TEI MWE

7.1. File name

7.2. Complete XML source

7.3. What the complete document contains

7.4. Reading the complete TEI document as a tree

7.5. From the TEI source to witness texts

7.5.1. Witness A

7.5.2. Witness B

7.5.3. Witness C

8. Common encoding errors

8.1. Placing the witness siglum directly in the reading text

8.2. Referring to an undeclared witness

8.3. Adding the number sign to xml:id

8.4. Using commas inside @wit

8.5. Repeating @wit

8.6. Leaving the reading outside the apparatus entry

8.7. Storing the lemma separator in the TEI source

8.8. Encoding a preformatted apparatus string

9. Structural and editorial checks

9.1. Structural checks

9.2. Editorial correctness

9.3. Three levels of verification

10. Inspecting the basic apparatus with ConTeXt

10.1. Purpose of the inspection test

10.2. Why the raw witness identifier is retained

10.3. ConTeXt source file

10.4. Compilation

10.5. Expected output

10.6. Processing path

10.7. Deliberate limitations of the test

10.8. A simpler fallback inspection test

10.9. The role of each ConTeXt setup

10.10. Source data and presentation remain separate

11. A practical apparatus checklist

12. What this guide has established

12.1. The completed progression

12.2. The essential distinction

12.3. Skills acquired

13. Next guide

14. Related pages

Navigation menu

Search

4.2. The `<app>` element

4.3. The `<lem>` element

4.4. The `<rdg>` element

4.5. The `@wit` attribute

8.3. Adding the number sign to `xml:id`

8.4. Using commas inside `@wit`

8.5. Repeating `@wit`