Publication of my digital edition – Working with TEI Publisher
In March, I started working on the DAHN Project and the Paul d’Estournelles de Constant corpus. Since then, as I presented and explained it in multiple articles, I have developed a model for the segmentation and the transcription of my corpus, as well as written several scripts: they correct and encode my texts; they encode the header and some of the metadata; they ease the encoding of special elements of my texts. Thanks to these developments, I already encoded over 200 letters from the corpus (minus the annotation, which is a task for later) and so, it is time to consider the publication of these letters.
Just like Letters and texts, d’Estournelles’ corpus aims to be viewed by an audience and shared with researchers, historians or war correspondence enthusiasts. In order to achieve this goal, we need to publish it and make it accessible via a website. But it is essential beforehand to think about how we want to publish it. We considered a few ideas to obtain what we wanted (building a website from scratch, doing XSLT transformations, etc.) and finally decided to work with TEI Publisher to establish our website, which will take the form of a generated standalone application that we will deploy afterwards.
What is TEI Publisher?
TEI Publisher is a tool made for the publication of digital edition projects. Its aim is to transform XML text into different outputs: firstly, a modern web page but also multiple exportable formats and ultimately to make all the transformed texts available in a generated application. TEI Publisher works with the TEI Processing Model. It is defined in the TEI P5 Guidelines and it consists of declaring model of action for elements present in the XML-TEI tree. An element will have the possibility to be affected by several models. It will act differently, according to various parameters, including the predicate associated with it (condition of application defined by an XPath expression). Relying on the technology of exist-db, an open-source software for databases built on XML, TEI Publisher treats these XML files like databases and its data, the elements, will then populate an HTML tree, with the help of an ODD1 file that registers all the declared elements. It is then associated to a template and it gives a specific output for the texts imported in TEI Publisher. Finally, a generated standalone application will display these transformations with all the different components of web pages. This includes tools to help with search and navigation for example. While following TEI Publisher’s rule of “standards, modularity, reusability and sustainability2”, the functionalities of the application are implemented with Web Components, which are part of the HTML5 specification. TEI Publisher contains many available components but it also offers the possibility to create your own components if you don’t find what you are looking for.
TEI Publisher targets both scholars and programmers for their edition project. For the former, it lets them publish their material without having to learn how to program and for the latter, it eases their work because it reduces the amount of code and thus improves the maintenance of the website and its code3. Furthermore, experience proved, through various projects, that TEI Publisher was indeed a powerful tool, generator of high-quality material, sustainable, whether it is XML-TEI or others XML formats4.
To share concrete and successful examples of its work, TEI Publisher features four demos on their website:
- An edition of Van Gogh Letters
- Documents to commemorate the 30th anniversary of the fall of the Berlin Wall
- Books from the Early English Online Books collection
- A collection of Shakespeare plays
These TEI Publisher editions are very different from one another in terms of content but pretty similar in the structure, even though the presentation and the search configuration differ. This proves that it is possible to customize your own website while maintaining the basic structure offered by TEI Publisher. This also represents extra support for later, when I will need examples to develop my own application.
Finally, TEI Publisher is an adequate tool for our work because it is well-maintained thanks to its developers and its community. It is regularly updated: once or twice a year, new features are added with the release of a new version and, at shorter intervals, minor versions fix bugs, improve the website and its functionalities5. It also benefits from a community, taking the form of an association created in May 2020 named e-editiones. This scholarly society is composed of owners of digital projects: “its goal is to empower digital editions […] by promoting open standards related to digital editions and advancing open-source applications based on them6”. It promotes the exchange of information between developers and users to help developing the toolbox (like sharing information when creating a new web component, as mentioned before) and ensure long-term availability of the digital editions.
Working with TEI Publisher
I have explained briefly the theoretical aspect of TEI Publisher and how it works. I will now explore practical aspects, by giving a description of the different steps I took to start working with TEI Publisher, from the installation to the creation of an application.
An easy installation
Installing TEI Publisher can take one to three steps, depending on what is already on your machine. In order to work, TEI Publisher requires either exist-db, either to run via docker, a software that allows the development of applications via containers. In my case, I used exist-db, so I will not explain how the latter works, but you may refer to the documentation here to explore it.
TEI Publisher needs exist-db to run and exist-db itself needs Java. I had neither on my machine so I installed them one after the other. This installation demanded three steps, but it was overall pretty quick. Java (minimum: 8; recommended: 11) only took a few minutes to download. Exist-db was also pretty easy and fast to install, mostly because all the different steps we need to follow are explicitly presented in the documentation. Once the installation of exist-db was complete, I could install TEI Publisher from there, logging with the admin user (no password needed), which then gave me an interface looking like the picture below.
exist-db Launcher (TEI Publisher is framed)
A good experimentation area
From the exist-db launcher, I can go to TEI Publisher and start experimenting with the application to discover what it can offer for a digital edition project.
TEI Publisher toolbox
There are two ways to experiment with the different options offered by TEI Publisher: either I test and play with the documents from the Demo Collection or I upload my own documents in the Playground and test the multiple ODD files associated to them.
In the Demo Collection are texts we have seen in the online examples, like the Van Gogh Letters. It is a pretty heterogenous collection made of plays, book-structured texts and several correspondences but written at different periods of time (15th, 16th, early 19th, 20th centuries, etc.). They don’t all have the same extra content: some have facsimile, translation, maps or extra metadata, which implies many varied ODD files and associated templates to display all of that. All those elements can be seen thanks to the Document View and also the settings panel, which gives me the possibility to select the ODD and the template for the chosen document. If I change some settings on a document, I see that the ODD and template are really specific because they don’t work on all the documents and they sometimes return an error message. From that Document View, I can also download the document in different formats, which is a plus from TEI Publisher: I have access to the XML file, an ePUB, a PDF, a TeX source and a PDF format from LaTeX. However, these formats are not always available; most are automatically accessible, but for some (the PDF LaTeX particularly), it is necessary to encode the metadata in the ODD (with the TEI element).
Once I experimented with the Demo Collection, I could upload my own documents and play with the ODD and template settings in the Document View to have a first look at what my text would look like with some special transformations. First of all, adding the document is very simple: XML-TEI are preferred because they will be easily and directly uploaded but some other formats are acceptable (ex: DocBook, DOCX) because TEI Publisher deals itself with the transformation to make it compatible for the application. Now that I uploaded my documents (a few letters from the corpus), I can test different settings.
Since the encoding follows the TEI guidelines, all the ODDs are compatible with the documents. Yet, it is when I test the templates that I see the specificities brought for the Demo Collection documents, because some options compatible with one of the documents are not for mine. These experiments gave me a first look at what we want or not for the website because I explored many options, some that I would not have thought of but then seemed pretty relevant for what we want to show.
A well-documented application
As it was shown, TEI Publisher is a convenient tool for working on the publication of a digital edition, offering many options to develop it. Furthermore, this is optimized by the availability of an extended and seemingly exhaustive documentation for the application and all the options attached to it. Before everything else, it is important to note that this documentation is easily reachable: from the navigation bar of the original website, from the navigation bar of TEI Publisher toolbox and in the toolbox alongside the Demo Collection and the Playground (as it is visible in the previous picture); it can be accessed at every moment if you are in need of help.
This documentation covers every aspects of the work on TEI Publisher. From the start, it contains a one-hour long video titled “Stay Home Learn TEI Publisher From Scratch” from a workshop organized in June 20207. It also contains a link to a workshop (see GitHub) that introduces TEI Publisher and explains how to work on an ODD to make some elements appear in the Document View. Then, one by one, all the aspects that will be useful to work with TEI Publisher are explained and detailed, like, for example, creation and modification of the ODD, handling page templates and pb-components (web component that acts like an HTML element on the page) and dealing with data and search configuration. Finally, this documentation contains a F.A.Q. and a roadmap that lists the future features wanted by TEI Publisher.
From the beginning, TEI Publisher is an intuitive tool, easy to use and quickly understandable, and the documentation reinforces that. It made me more comfortable with the creation of my customized ODD and later on, the generation of my application, because I know that if I encounter some trouble while developing one element or the other, there is a documentation that will probably be able to solve my problem.
Drafting the website: creation of a customized ODD
After doing an extensive reading of the documentation and testing the numerous documents and settings proposed in the Demo Collection and those that I uploaded, it is time for me to start developing my own ODD, adapted to my corpus. There are two ways to do it: I can either start an ODD from scratch or reuse one of the pre-installed sample that I save under a new name and work from there.
In order to really understand how an ODD works and is composed, I decided to start from scratch and add every element that I needed, one by one, and specify the model each time I needed it. The ODD customization consists of declaring every element present in the TEI documents attached to our corpus in order to define how it would be transformed and how it should be displayed. To do so, TEI Publisher offers two ways: a manual work on the ODD, via Exide, or a visual editor, that is preferred in the documentation, because considered as “the fastest and safest way to edit your ODD8”. Since I am an unexperienced user, I choose the safest option and started using the visual editor.
ODD visual editor
With this editor, the ODD is easier and faster, mostly because when one element from the TEI Guidelines elements is added, the visual editor usually sets a default behaviour.
The behaviour of a model “names the process or function which this processing model uses in order to produce output.9”. For examples:
- <TEI> = “document”
- <p> = “paragraph”
- <teiHeader> = “metadata”
- <note> = “note”
- <pb> = “break”
Thus, when building the ODD, most of the elements don’t require a lot of work, because all I need to do is add them and their behaviour is already determined and adequate.
However, it is not the case for every element in my TEI document and some need either a different behaviour than the one defined (e.g.: <pb>, <note>) or a special display that demands more information (e.g.: <hi>, <add>, <del>, <p>). I changed <pb> from “break” to “omit” so that the tag does not appear in the display even though it is taken into account. <note>, according to the encoding of my corpus, is also changed because I used the tag as a way to display page numbering and it can’t appear at the bottom of the page with a reference. Yet, I also have footnotes in my corpus that have to be specified in the transformation, so I need to have both behaviours declared, which is possible in the ODD. An element can declare several models, everyone will need some specification that will appear in the form of a predicate and corresponding information in CSS and HTML (when should it be applied, what is supposed to happen and how should the text be formatted?). More importantly, it is essential to be careful about the order in which the models are declared for each element. It needs to go from specific to general because that is how it will be read by the machine and if the general predicate is considered first, the element will be displayed without the specific formatting that it should have.
To build my ODD with the specific predicates, I used multiples sources: my script and corpus encodings to get all the specificities from the elements in my encoding, other ODDs to see how the models were declared, the documentation because it contains examples and exercises to declare predicate and associated input and CSS documentation to add my own rendition when needed. I specified elements where the model has text alignment, text underlined, strikethrough and/or indented, etc. For example, I added a specific rendition for elements with a @hand=“#annotation”attribute, since they signal parts of text written in cursive. I wanted them to contrast with the rest.
Every time a processing model is addressed, it is possible for me to see if it appears as I want it according to the content of my corpus’ letters. I go to the Document View with one of my documents and select my ODD in the settings. From there, I can check on my customization and change the inputs every time it is necessary. Once I am satisfied with the output, I can consider my ODD ready and start generating the app.
Drafting the website: generation of my application
It is recommended to have a complete ODD to generate the application but it is not mandatory, since it is still possible to change the ODD afterwards, via Exide, manual changes and recompilation. The same goes for page templates: it is still possible to change the default page template or its content once the application is generated by going into the code and tweaking it (which requires however some basic knowledge in HTML and other programming languages).
As soon as I have a satisfying ODD and a page template, I can generate my application. It is a pretty simple step if you have read the documentation because all the elements required and useful are mentioned in it and it even contains a gif showing the steps to generate the application. It is available on the homepage of TEI Publisher and in the documentation.
Once generated, the application will be available in the exist-db launcher and it will pretty much look the same as the TEI Publisher toolbox.
exist-db Launcher (the app is framed)
Homepage of my generated application
From the homepage and every other page in the application, I have access to the “Admin” button in the navigation bar, which allows me to do three actions: download the app in a compressed .xarpackage, edit the ODD or have access to the API Documentation, which will show the API content of my app (which is editable via Exide).
In the Document View, the appearance depends on the ODD and page template declared by default but it is possible via Exide to specify other ODDs or template for some specific pages of the application. Despite the fact that this and other elements can be changed in the generated app, there are still some defined files that should not be touched. The documentation specifies which ones are concerned, in order to stay linked to TEI Publisher and not break the application if we need to download upgrades. Globally, a lot of files are still editable, like the templates, some configuration for searching and indexing, resources and API functionalities. The documentation also explains how to add or change certain elements to improve or enhance the application and furthermore, I have, at my disposal, the demos from TEI Publisher with their code available in a GitHub repository or in Exide, that I can use for help and/or ideas.
I now have a functioning application where I can upload my encoded corpus and display it as I want. It is pretty basic and only conveys, for now, what TEI Publisher offers, but it can still be improved. Once I dive into the code and do changes to the templates, the proposed view, the metadata, etc., I can have a website hosted by TEI Publisher but with much more than the basic templates proposed, just like Van Gogh Letters and When the Wall Came Down did. I will also need to export and launch the app (which is another element explained in the documentation), in order to have it available for everybody on the web and not just on a local server on my machine.
- An ODD, or One Document Does it all, is used to generate multiple outputs that will include a documentation for elements, attributes, etc., descriptive documentation like tag description linked to the TEI Guidelines and declarative code for one or more XML schema languages. Here, it will define the rule of transformation of the XML source file into HTML. [↩]
- What TEI Publisher does … : https://teipublisher.com/exist/apps/tei-publisher/doc/documentation.xml?odd=docbook.odd&root=2.5 [↩]
- Ibid. [↩]
- Ibid. [↩]
- Versions : https://teipublisher.com/exist/apps/tei-publisher/doc/documentation.xml?odd=docbook.odd&root=2.5.8 [↩]
- https://e-editiones.org [↩]
- Quickstart : https://teipublisher.com/exist/apps/tei-publisher/doc/documentation.xml?odd=docbook.odd&root=2.7 [↩]
- Modify the ODD : https://teipublisher.com/exist/apps/tei-publisher/doc/documentation.xml?odd=docbook.odd&root=2.11.9.6 [↩]
- <model> : https://tei-c.org/release/doc/tei-p5-doc/en/html/ref-model.html [↩]
OpenEdition suggests that you cite this post as follows:
Floriane Chiffoleau (December 4, 2020). Publication of my digital edition – Working with TEI Publisher. Digital Intellectuals. Retrieved October 6, 2024 from https://doi.org/10.58079/nmyw
Thank you. By the I would like to know where did you hosted your corpus? We too have a corpus of TEI documents in Sanskrit and other languages(Ancient Indian languages). Philosophical works of a Indian saint and social reformer named Ramanujacharya lived between 1017–1137 CE. I have locally installed existDB and Tei-Publisher and have created by ODD and all the things. But I need some guidance on publishing the works in WWW.