Archives Online offers hosting in cooperation with e-editiones

2021-03-28, Wolfgang Meier

In cooperation with e-editiones, Archives Online is building an infrastructure for digital scholarly editions based on TEI Publisher and IIIF. It is offering comprehensive, long-term support and maintenance to keep digital editions from going dark. The offer is available to all interested editions world-wide.

The offer will be complemented by a portal, which allows users to search across all editions participating in the service. The portal application has been developed by e-editiones, Archives Online and the Staatsarchiv Zürich, and will go online as soon as the first editions are ready for publication. All code will be made available as free software. The distributed search feature was based on earlier work financed by the DIPF Berlin (Leibniz Institute for Research and Information in Education), and the Karl Barth-Gesamtausgabe supported the server set up and automation.

The goal is to provide an easy, long-term hosting option for editions based on minimal, well-documented requirements: ultimately any edition which complies with the recommended practices can benefit from the hosting offer and participate in the portal service.

If you are interested in having an edition hosted, please contact Archives Online. The service will not be for free: any serious long-term hosting has to cover certain maintenance costs if it wants to follow more than an "install and forget" policy. But we’re confident that our solution minimizes the costs while providing the best possible service, in particular if you’re looking towards long-term availability.

Technical Background

e-editiones central goal is to provide editions with a sustainable publishing solution which ensures long term availability with minimal maintenance. With the redesign of TEI Publisher 6 and 7, we prepared the necessary technical foundations: all editions generated by TEI Publisher now share a common API.

With the new version 7 it became possible to:

  1. host multiple editions created with different versions of the libraries side by side,
  2. simplify the update procedure to make sure editions benefit from new developments while keeping maintenance costs very low,
  3. search across local and distributed editions (hosted on a different server) by leveraging the shared API

Also, despite looking different on the surface, the building blocks for any TEI Publisher-based edition are the same, which allows server administrators to create automated setup and maintenance routines.


Among many other things, TEI Publisher 8 will further improve the architecture by introducing more generic concepts for persistent URLs, navigation and addressing documents, allowing editions to use an addressing scheme which better reflects the logic of the edition rather than technical requirements.

A direct integration with git will allow editions to update published data without having to touch the command line.

The upcoming version will also include index configuration and API endpoints for local and distributed portal search, so generated editions can automatically participate in a multi-edition portal like sources-online.

With these low-level technical questions solved, e-editiones is now also putting a strong focus on describing the practical recommendations for the encoding of texts. The idea is to create a set of best practice guidelines for corpora with a pledge that any text following these guidelines will look good out of the box when rendered via TEI Publisher and will be ready for incorporation into the search portal. Initial work is carried out now and we expect a community meetup soon to discuss on a broader forum.

This way we aim to: flatten the learning curve for many projects starting with TEI encoding, reduce the amount of customization work required for an edition, allowing users to publish materials with minimal effort, and assure that the project data is ready to be integrated into larger scale search portals. Needless to say, recommendations we have in mind are intended only with an eye towards interoperability and do not limit in any way customization capacities already embodied by the TEI Publisher approach.

Newsletter 2021/1

2021-02-02, Andreas
Tags: ,

We’re happy to send our first newsletter covering the past year of activities and developments within e-editiones and would like to encourage institutions or individuals who are not yet members to join forces.

e-editiones as a Society

The e-editiones society was founded on 4 May 2020 by more than 20 international partners. Our institutional members are academies, archives and libraries, edition projects and their sponsors, as well as companies. Among individual members we are proud to count archivists, librarians, editors, researchers from the (digital) humanities, and software developers. After our first attempt to obtain a non-profit association status from the St. Gallen tax office failed, e-editiones was recognized as a non-profit association with tax exemption, following an amendment to the statutes (5th November 2020). A huge thanks to the Karl Barth Foundation for generously sponsoring the necessary legal advice. Building on these foundations and developments and events listed below, our still young society is off to a great start. We hope to broaden the community and increase our membership in 2021.

More Information

2020 Events

e-editiones organized various meetings and workshops in 2020 for members and the wider community to get to know each other and exchange ideas.


  • 04.05.2020: Virtual foundation of e-editions and first community event for members
  • 18.05.2020: First Public Community Event: Presentation of e-editiones by Andreas Kränzle with a short introduction to TEI Publisher for digital editions by Wolfgang Meier, discussion moderated by Joe Wicentowski Video
  • 20.10.2020: TEI «Vanilla» by Magdalena Turska Report


  • Three-part online Course: Learn TEI Publisher by Wolfgang Meier
    • Learn TEI Publisher 1: «Stay Home Learn TEI Publisher From Scratch» , 8th Jun 2020 Video
    • Learn TEI Publisher 2, 15th Jun 2020 Video
    • Learn TEI Publisher 3, 22nd Jun 2020 Video
  • Music is in the air – MEI and TEI Publisher by Giuliano Di Bacco and Dennis Ried, 8th Jul 2020 Video
  • Common eXist-db/TEI Publisher. Deployment Scenarios by Olaf Schreck and Lars Windauer covers different deployment scenarios of eXist-db and TEI Publisher, 9th Sep 2020 Video
  • Open Source Advent: Presentation of a number of open source developments, 11th – 31st Dec 2020 Link

More Information


The association immediately set up communication facilities for its members and the community. For technical questions about TEI Publisher, the central communication channel is Slack. Recurring issues and questions are incorporated into the new FAQ page. For announcements and important messages, we use Twitter. Follow us!

More Information

TEI Publisher Developments: Versions 6 and 7

In 2020 two major versions of TEI Publisher were released: versions 6 and 7. The plan for these versions was born during a meeting in Basel in November 2019, when several Swiss edition projects using TEI Publisher came together to discuss how the software could be developed into an even more sustainable platform. A number of them later became founding members of e-editiones. Their primary goal was to enable institutions to manage and maintain a larger number of editions, either on the same or several servers. To reduce maintenance costs, keeping editions up to date with newer TEI Publisher versions needed to be as simple as possible. Editions relying on different versions needed to be able to run alongside each other.

Two areas had to be addressed to achieve these goals:

  1. On the client side TEI Publisher was already a collection of small, modular web components, which together formed the user interface. These components had to be extracted into a separate library, so projects could benefit from bug fixes and new components without having to update the rest of the edition’s application.
  2. On the server side TEI Publisher needed a well defined API. Such an API would provide a standardized communication channel, through which the web components on the client could talk to the server. To accommodate future updates and support backwards compatibility, the API would need to be versioned, ensuring that both sides could speak the same language.

Fortunately the Swiss Nationale Infrastruktur für Editionen – Infrastructure nationale pour les éditions agreed to support the outlined ideas, funding a substantial part of the work.

With the release of TEI Publisher 7, both areas mentioned above have been addressed and the goal has been fully reached.

Contributions also came from member institutions: the Collection of Swiss Law Sources Online and the St. Galler Missiven were built on an early version of TEI Publisher 4. Both funded a major update of their code to version 7. A number of regressions and new bugs were encountered during the migration, and appropriate fixes were contributed back into the TEI Publisher code base.

The Karl Barth Gesamtausgabe likewise served as a test bed during TEI Publisher 7 development. Furthermore, the Karl Barth project financed the Microsoft Word to TEI transformation, which is now part of TEI Publisher.

The source code of TEI Publisher and its related repositories have been moved under the roof of e-editiones and are hosted within its GitHub organization.

Other Software Packages

Beyond TEI Publisher itself, e-editiones released a number of other software packages:

  • The Open API routing library at the heart of TEI Publisher 7, called Roaster, proved to be useful even outside the humanities and has already been adopted by a project in the medical realm.
  • Born out of the Karl Barth Gesamtausgabe, e-editiones published an extension for the Visual Studio Code editor to help editors work on TEI. This includes an entity explorer to help with the markup of entities in a text by querying external authority databases from within the XML editor.
  • The Cross Search package provides a blueprint for a portal incorporating multiple editions, supporting cross-edition search facilities. This will become the basis for future hosting services.

Community Contributions

Last but not least, we would like to point out the many contributions we received with respect to translations: TEI Publisher has now been translated to more than 20 languages!

We hope to see similar interest in other areas, e.g., the newly established FAQ website. We would like to encourage everyone to add entries and turn this into a knowledge base for all users. It already hosts questions and answers concerning encoding, workflows, or best practice recommendations.

The Future

Continuing our cooperative development model, the following new components and features are scheduled to appear in the forthcoming minor version of TEI Publisher:

  • A component for displaying mathematical formulae, sponsored by the Bernoulli project (Uni Basel).
  • A feature to automatically register persistent DOI identifiers with every resource uploaded to TEI Publisher (financed by the DIPF).

e-editiones is actively apply for funding: a first proposal has been sent to a Swiss foundation, and we’re waiting for feedback. The features we hope to obtain sponsorship for include:

  • Better navigation within an edition by allowing arbitrary identification schemes for resources.
  • Speaking and bookmarkable URLs.
  • Improved accessibility.
  • A timeline component.
  • Components to improve the editorial workflow:
    • Git integration into the user interface for synchronization.
    • An annotation feature allowing editions to perform semantic markup tasks directly on the rendered text.

If you have other features on your list, please do not hesitate to propose them. We can achieve more at lower costs if we all work together. If you need a certain feature and plan to apply for funding, why not ask other projects which may have similar requirements? e-editiones is a welcoming umbrella under which your project can come together with other projects from different academic disciplines, coordinate needs, and potentially convince funding agencies to look beyond the perspective of a single project.

1 Comment on Newsletter 2021/1

Roaster: an Open API Router for eXist

We’re happy to announce that the request routing library, which was originally developed for TEI Publisher 7, has been released as a separate package with extended functionality. The library, called roaster, is generic and can be used for any eXist-based project. It implements the Open API 3.0 standard to support well-documented, versioned and formally specified APIs.


In previous versions of TEI Publisher, clients (i.e. your web browser) would communicate with the server by directly calling a variety of XQuery scripts. The server-side API, if you can even call it one, was thus scattered over many different files. Finding your way through the code, figuring out what parameters are expected or how the response should look like was rather difficult. Overwriting the default behaviour – e.g. to replace the generated table of contents – required substantial coding skills. The scripts also changed between TEI Publisher versions. So, if you were working on a standalone edition generated from Publisher, updates could be tricky.

With TEI Publisher 7, the entire server-side API can be viewed on a single documentation page. It clearly describes the URL paths you can use, as well as any parameter you can pass in and the type it should conform to. One can also see the different possible responses and what kind of content they would return.

The new API

Looking at the first route of the documents section in the API (see screenshot below), it is easy to construct a URL which returns the source XML: the path template to use is /api/document/{id} and {id} should contain the path to a document – relative to the data root of TEI Publisher.

Documents API screenshot

So to retrieve the TEI/XML for Graves’ letter, located in the file path test/graves6.xml, we can use the following URL:

Note that the / in the path needs to be URL encoded with %2F. This is a requirement of the Open API specification.

If instead of the TEI/XML we would like to see the letter rendered to HTML, we can use the third route in the list and simply add /html to the end of the URL:

or if we prefer a PDF:

For sure, as an ordinary user, you don’t need to know any of this: using the web interface of TEI Publisher, the web components on the page take care of constructing and calling above URLs for you. But if you are a developer, having a well-defined API is a game changer. Just imagine that you want to support your co-workers with a script which allows them to preview a local TEI document as HTML on the fly: sending the content of the document with an HTTP POST request to /api/preview is all you need! Our Visual Studio Code plugin does it like this.

You can use any script or programming language you like, say bash, python, perl – you name it. And because Open API is a widely used standard, there are plenty of tools for documentation, testing or code generation. The API documentation page in TEI Publisher is generated by such a tool (Swagger UI).


roaster is essentially an implementation of the Open API standard in pure XQuery. It reads the formal API specification (in JSON format) and determines for each HTTP request coming in, which route to take. It will also check if the parameters, headers or request bodies passed in comply to the rules given in the definition of the route. An error will be generated if the request is not in compliance with the definition, e.g. because a required parameter is missing or has a wrong type. It can also fill in default values for parameters, enforce correct content types for the response etc.

From a developer perspective, this means you don’t have to worry about parameters. Your handler function will receive a single parameter, containing all the necessary information about the request and you can safely assume that it complies with the spec you provided.

If you are interested in the details, please refer to the README. For a TEI Publisher-related example, check out the FAQ article, which describes how to replace the default table of contents with a custom one.

Roaster 1.0.0 can be installed into your local eXist via the package manager in the dashboard. TEI Publisher 7 shipped with a slightly older version, 0.5.1., but you can run both versions side by side.