An Online Digital Critical Apparatus

The online Apparatus Explorer is a web app implementation of my standalone desktop version.

A Little Background on the Apparatus Explorer

One of the tools I use every day while I'm writing up my doctoral thesis is a little desktop app (Apparatus Explorer) that I developed for easily visualizing and editing an XML TEI encoded digital critical apparatus. TEI is human readable on its own, indeed, TEI encoded documents are commonly produced by humanities scholars whose specialty is far from software development. On the other hand, non-styled TEI is not really meant to be published 'as is,' but its value comes from carrying additional data along with the plain transcription (corrections, reading types, etc.). The Apparatus Explorer is one way to take the text and extra encoded information from a collation file and display it back to a human editor as an intuitive and useful digital critical apparatus.

What the Apparatus Explorer Does

In this online version of the Apparatus Explorer, a (logged in) user can upload a collation file. The file will then go through some processing in the server:

From here the files are ready to be viewed in the Apparatus Explorer. If any local stemmata have been encoded, these are displayed as graphs. In fact, one of the main goals for this project was to easily encode (i.e. by clicking buttons rather than hand encoding) local stemmata for each variant in preparation for using the collation file as input for the open-cbgm. Additionally, the Apparatus Explorer enables simple addition of reading types (e.g. lacunose, orthographic, etc.). All of this is built into the desktop app.

I am very pleased to offer the same functionality as a web app. A web app has several advantages over the desktop application:

Check out the Demo!

I'm sure you will understand why only logged in users may upload their own collation files. However, I have one of my own collation files uploaded and ready to be parsed and viewed.

Demo Tutorial

Go to the demo at

1. select an available collation and click 'Load.' At the time of writing this post I've only added one to the demo.

Apparatus Example with arrow pointing to load button

If the collation file contains multiple verses (I work a chapter at a time), any verse can be selected from the dropdown menu or adjacent verses can be selected by clicking Prev and Next.

Upon loading, the variation units, basetext, and indices should be generated. Think of this as similar to the ECM's layout. Each word in the basetext is given an index number, so every variation unit can be identified as a range of these index numbers. The basetext is reconstructed from the TEI file by piecing together all the readings tagged as belonging to the basetext. In the case of the example file, the NA28 was used as the basetext.

2. click on one of the variation units.

apparatus explorer with arrow pointing to variation units.png

Upon clicking on a variation unit, the rest of the explorer will generate. Notice that the selected unit is highlighted in the basetext.

3. Add a local stemma information by clicking on a reading to designate as the 'from' node.

apparatus explorer with arrow pointing to selected unit and local stemma editor.png

After clicking on a 'from' or starting node, the available 'to' nodes will appear. Make your selections and then click 'ADD.' You should see the graph update; when the verse is saved (a feature not available in the demo), the original collation file will be updated with the edits. These choices become powerful in combination with the open-cbgm.

4. Change or add a reading type.

apparatus explorer with arrow pointing to reading type editor and to updated reading

Finally, update a reading by first selecting the reading identifier, selecting a reading type, and then clicking 'ADD.' Most readings do not need a type encoded, but they are helpful for several things. First, adding a type helps to clearly distinguish between lacunose and omitted text. Second, the open-cbgm can be configured to count different reading types in different ways. For example, one may want to exclude minor spelling differences before calculating pregenealogical coherence. If that is the case, then readings labeled "orthographic" will be considered to agree with their parent reading.

Future Plans

Feedback is appreciated!

This is a niche tool. It is limited to those who have their own TEI collation files, encoded by hand or from the Collation Editor. But if this tool finds its way to another person doing similar research, please let me know what works and what does not.

I would love to see other critical apparatuses displayed in this way.

Return to blog