Basic principles

The TEI Critical Apparatus Toolbox (TEI CAT) is a simple tool offering an easy visualization for TEI XML critical editions. It especially targets the needs of people working on natively-digital editions. Its main purpose is to provide editors with an easy way of visualizing their ongoing work before it is finalized, and also to perform some automatic quality checks on their encoding.

To complement this page, readers might be interested in consulting the article "The TEI Critical Apparatus Toolbox: Empowering Textual Scholars through Display, Control, and Comparison Features", published in the Journal of the Text Encoding Initiative in 2016.

The main reasons to use the TEI Critical Apparatus Toolbox are:

• To simply display your edition in a reader-friendly manner, even before you have completely finalised it.
• To perform quality checks on your encoding, to check if you haven't forgotten to list a witness here, or listed the same twice there.
• To display the text of one or more specific witness(es).
• To get a printable PDF and a LaTeX file from a TEI XML file.
• To annotate an image in XML TEI.
• To get some basic statistics about your TEI file (which tags and attributes are used in the files, which words appear in the file, with which frequency etc.)

Requirements

• Your edition must be encoded in TEI with the Parallel Segmentation method.
• You simply need a recent browser to access the application and upload your XML file (nothing to install).

For testing purpose, you can download this test file, a pseudo-edition encoded in TEI and illustrating most of the cases handled by the Toolbox.

Simple visualization

Tools like Diple or the Versioning Machine are very efficient for finished editions, but they may not be well adapted to ongoing work. For instance, an ongoing edition is likely to present only app elements with only rdg children, or to present a mix of app elements with only rdg children and others with both a lem and rdg children. Proposing a visualization for such encoding is not easy, because there is no base text (yet).

The TEI Critical Apparatus Toolbox accepts both types of app elements (rdg only, or lem and rdg), even in the same file. It will display each type slightly differently:

• In both cases, the content of lem and rdg are highlighted, with a white background.
• When the app contains a lem, only the content of the lem is displayed in the text (in order to make the apparatus lighter and more readable), and the variants appear in a pop-up note. To see the note, simply click on the ^↑ sign just after the content of the lem. To make the note disappear, double-click on the pop-up. Example:
  ... Eccli. VIII^↑VIII F K1 V] XVIII K2...
• When the app contains only rdg, the content of each is displayed, in the order of appearance in the app. To make the text better readable, curly brackets open and close each series of rdg belonging in the same app. For clarity's sake, empty readings are materialized with a minus sign, "-". Example:
  ... collegium {- K1 K2; vel F V} capitulum...
• When the encoding uses reading groups (rdgGrp), the content of each rdgGrp is displayed between bold double parenthesis. If the rdgGrp contains a lem, its text is underlined:
  {((exhortatio K1; exortacio K2)); ((sermonis F; sermonem V))}

In the toolbox, you will have the option of showing or hiding the page breaks, either all of them, or for a particular witness. To do so, you will need to have used the witness ID in the @ed of the pb tag.
The page breaks are displayed in a slighly different manner if you choose "all" or only individual witnesses.
If you choose to display all page breaks, they will appear inline, keep the text readable. Example:
pro inquisitione generali hereticorum vel aliorum [K2 : 311v] enormium facienda.
If you choose to display pagebreaks for an individual witness, we assume that you are particularly interested in it and we display the page breaks more visibly, with a thin blue line representing each break. Example:
[F : 156v] Incipit tractatus...

Checking the consistency of your encoding

Encoding a natively digital critical edition with a positive apparatus, where all variants are mentioned for all manuscripts, is a good way to make sure you have not forgotten any reading in any manuscript. This is a useful practice during the preparation of the edition, even if you intend to mention only variants from a default lemma in your final edition.
It is frequent for editors to make mistakes, like introducing a typo in the siglum of a manuscript, or simply forgetting to mention which reading is found in one of the witnesses. This is why critical editions require many proofreading sessions. The TEI Critical Apparatus Toolbox will not replace those sessions, but it can help you perform consistency checks on your encoding.

Features for editions with a "positive" apparatus

If you have made a "positive" apparatus (all the available witnesses are expressly mentioned in each app), the TEI Critical Apparatus Toolbox can identify all the apparatus entries wich do not give a reading for each of the witnesses you will have listed in a listWit in the header. To perform this verification, check Highlight apparatus entries that do not use all witnesses? in the Toolbox. The incomplete apparatus entries will be highlighted in red. Example for an edition with 4 witnesses F, K1, K2, and V, where no reading has been noted for V:
Nos quoque {oramus F; eramus K1; obsecramus K2} ut servo...
You are also offered the option of highlighting only the apparatus entries that do not use a particular witness. This can be useful to avoid noise when you have several unfinished collations. Each witness is assigned a different colour automatically. There are 20 assigned colours, if you have more than 20 witnesses the colour cycle will begin again.

Note that the Toolbox is capable of dealing with encoded lacuna. If a witness is incomplete, and its lacunae have been encoded with lacunaStart / lacunaEnd, the apparatus entries appearing in the text between those two elements will consider that the correspondig lacunary witness is mentioned and not missing. On the other hand, if within this supposed lacuna an apparatus entry mentions the incomplete witness, the Toolbox will point it as a case of witness appearing twice.

Features for editions with a "negative" apparatus

If you have a "negative" apparatus (defaut text in a lemma without @wit), you can use the TEI Critical Apparatus Toolbox to highlight apparatus entries that DO mention a particular witness in the variants. In the toolbox, select the witness in the section Highlight apparatus entries that mention a particular witness?. Example for an edition with 4 witnesses F, K1, K2, and V, where you are looking for all apparatus entries mentioning K1:
... secundum Boetium in principio De Trinitate^↑Trinitate] unitate K1 K2, ...

Other controls

The "Various controls" rubric in the Toolbox lets you select other options which might be useful in both types of encoding: highlighting app entries that contain a lem, or app entries that contain only rdg elements, or app entries where the same witness appears more than once, or where no witness at all is mentionned (probably due to an encoding mistake, in both cases).

Displaying your text according to one or more specific witness()es)

If you are interested in displaying the text of your edition according to one or more of the witnesses, go to the "Display parallel versions" tab, upload your XML file and choose the sigla of the witnesses you want to display. This feature is available for both positive and negative apparatus. You also have the option of displaying the "Critical text" alongside the text accoding to particular witnesses.

When you click on "Submit", parallel versions of your text will be displayed in columns, each showing the text according to a different witness.

In these columns, the text is presented in a similar fashion to the "Check your encoding" display, but when there is an apparatus entry, the text shown is systematically the one of the chosen witness, whether or not it is a lemma. This means that the other readings (including the lemma) appear only in the apparatus notes. To help you place each reading of this witness in relation to your edition, there is a colour code for those readings:

• when this witness has the same reading as the lemma, the text is highlighted in white
• when this witness has a different reading from the lemma, the text is highlighted in orange
• when there is no lemma for an apparatus entry, the text of the witness is highlighted in yellow
• when an apparatus entry does not give any intelligible reading for this witness, question marks are highlighted in red ????? This means there is probably something wrong with the way this bit is encoded.