This post is meant for everyone interested in working with digital editions and hopefully provides a place to start. I will explain how I got started during the pandemic and where I found the most useful information and tools to edit with. You will soon notice, however, that there is much more here than just some pointers on the XML format and TEI standard. For me, producing elaborate XML files was not enough as I wanted to show what I was doing to my colleagues but also my family and friends. This resulted in learning how to present digital editions as well and eventually host them, which involved learning to use various types of software and even hardware (with The Salomon project as end result). The headings in the post will describe certain goals I had and what I needed to get there.
Keep in mind that this is not so much a tutorial on how to set up your own digital edition as a collection of useful links that will (hopefully) save you a lot of time establishing and reaching your own goals.
If you have any questions or feedback, you can reach me via email or Twitter.
Editing
As an introduction to XML and the TEI standard, I used an online course called ‘Digital scholarly editions: manuscripts, texts and tei encoding’ on the platform #dariahTeach. It consists of a series of six youtube videos in which two humanist scholars explain the central concepts of creating digital editions, explain commonly used terminology and take you through the process of making an edition. There are also small assignments, which will help you get started right away. I found it a useful introduction because it explains the reasoning behind encoding and standardization.
Software
Editing XML files can be done in different ways. Below I will list some programmes I used for this purpose and tell you why you might want to try them yourself. In the end, it comes down to your requirements and personal preference.
Oxygen XML Editor
For encoding XML files the course uses Oxygen XML Editor. Because it is developed for this purpose, it works great out of the box. Oxygen is a paid piece of software, however. Luckily it is often part of the software that universities offer to their students and employees.
Visual Studio Code
Although Visual Studio Code is not specifically designed to edit XML files, it does work and works quite well. Visual Studio Code is an advanced source code editor that is free. Due to its broad functionality, it is very flexible but can be a bit overwhelming at first. For that reason, it might take some time to get used to.
Notepad++
I also found success with Notepad++ and the plugin XML Tools, which is much more straightforward. It is free and requires little effort to set up, but do not expect any bells and whistles.
Other useful tools were:
Presenting
After finishing the course (see above) I was dissatisfied with the result, mainly because it did not result in anything you can show someone who is not familiar with XML encoding (i.e. everyone around me). So I decided that I had to present the edition I made somehow. I wanted to control the whole process, mainly because I had seen other projects where there the communication between the scholars on the one hand and the software engineers on the other was difficult and quite time-consuming. Via an impressive digital edition of the letters of Vincent van Gogh, I stumbled upon TEI Publisher, which eventually turned out to be exactly what I was looking for.
TEI Publisher
In short, TEI Publisher is an ‘instant publishing toolbox’ that runs inside a database called eXist-db. It enables you to turn your XML files into rather nice-looking digital editions without too much trouble. There is another online course (in three parts) found on YouTube made by e-editiones, a non-profit organisation meant to empower digital edition projects. During the course, you will learn how to set up your first digital edition (including a IIIF facsimile) from scratch, which can then easily be modified. As it involves some XML, HTML, CSS and even some XQuery I recommend doing the introduction to digital scholarly editions first (mentioned at the beginning). Once you understand the structure of these files and how XQuery works, it is easier to implement changes to your own edition.
Useful tools were:
- TEI Publisher documentation is a great reference and demonstration of everything that is possible with this particular toolkit (see various examples of editions here).
- e-editiones slack channel is a place where you find other people interested in TEI Publisher and have the opportunity to ask them questions. If you ask concrete questions you usually get a quick answer and people there can be quite helpful. It will not solve all your problems, however. Remember that your favourite search engine is your friend in this case.
- CSS reference is a great index of all CSS properties and helped me out a lot.
- TEI Guidelines are useful for thinking about your own edition and the information you might want to encode.
Hosting
One aspect that is not addressed in the two courses I mentioned is the hosting of your digital edition. Often this is considered the realm of the university IT department, who you send an email to and then might help you set up your project online. As I wanted to control the entire process, I also wanted to organise my own hosting. Even though I did have a tiny server running in my own home at some point, it did lack the power I needed for a smooth TEI Publisher experience. Unless you are willing to spend some serious money and enjoy tinkering, I reckon that it is not worth the effort. Still, setting up my home server was helpful because it was a great test environment and introduced me to the world of Docker and Linux. Learning the basics of both is valuable because it will help you properly develop, store and set up your digital edition. In this way, you will be able to set up a digital edition (with just a little help from the IT department) in no time.
Docker
As you progress through the online course, you will learn how to run eXist-db on your computer and install TEI Publisher as an application within the database. While this is useful, I found working on the edition much easier within a containerised environment. Docker is virtualisation software that creates a ‘container’ that contains everything your application needs to run. I found running eXist-db and TEI Publisher in a small virtual container way more effective because it provided me with an easy way to back up my data and the opportunity to get it running on different devices. Instructions on how to pull, run and access a Docker Image of TEI Publisher are found here.
Once you started working on your edition, it might be a good idea to start pushing your images to Docker Hub and, in this way, create a backup. I have deleted my own project data at least twice (updating TEI Publisher within your image is very dangerous - do not do it without a proper backup!), so I learned this lesson the hard way. Therefore, make it a habit to push your image to a registry such as Docker Hub or GitHub regularly. Once you do this, it is rather easy to deploy your edition on a server, which I will explain below.
With regard to Docker, also useful was Docker for beginners, a tutorial that will introduce you to the basics of working with Docker.
Finally, if you are interested in looking at the digital edition I made or using it for some experimentation, you can access all data via its page on Docker Hub. There you will also find instructions on how to pull and run the image on your computer.
Server
Running a digital edition proved to be relatively easy with Docker and a server. For this step, you might need to ask your IT department for some help. I asked for a headless Linux server connected to the interet on which I had permission to run Docker. The IT guy then asked how much computing power I needed. I gave him an estimate based on the home server I had running, which works fine. Naturally, results may vary based on the needs of your edition. The configuration I use is as follows:
- OS: AlmaLinux 8.6 (this can be any distribution of Linux)
- CPU: 2.6 GHz (2 cores)
- RAM: 3.6 GiB
- HDD: 30 GiB
Once this is up and running, I use some programmes (almost all Docker Images) to manage and run my edition. I will list them below, along with some basic information on why you might need and use them.
PuTTY
Accessing your (external) server is done via a terminal simulator such as PuTTY, the only programme that is not a Docker Image on this list. In PuTTY you can use the details you receive from your IT department to connect to the server and execute the commands needed to pull and run the images listed below. For managing multiple servers at the same time use Solar-PuTTY.
eXist-db with TEI Publisher
The instructions I mentioned above for running an image of eXist-db and TEI Publisher locally on your computer, can also be used to pull and run an image on your external server. The same goes for a digital edition you might have pushed to Docker Hub yourself.
Portainer
Portainer is a tool to visually manage your Docker Images on the web. As using command line can sometimes be confusing, especially when you need to modify certain containers, having a graphical user interface to interact with them can be useful. This video explains how to install portainer (as a Docker Image) and even teaches you how to expose it safely to the internet (see below).
Nginx Proxy Manager
In order to point the web address of your server to the container that runs the image of your edition, you can use Nginx Proxy Manager. With this tool, you can point your main address (www.example.com) to the port that you assigned to your image (most likely 8080). How to do this is explained at the end of the video mentioned above.
Netdata (optional)
If you want to make sure that your server is running smoothly and has enough juice to run your digital edition, you can use Netdata. This monitoring software will provide you with everything you need to know.
Watchtower (optional)
Watchtower is a handy tool to keep all images running on your server up to date. A short guide on how to do this is found here.