Annotation editor released with new TEI Publisher 7.1.0

Answering the secret dream of many TEI users, the new TEI Publisher version 7.1.0 incorporates a — beautifully simple to use, yet powerful — way to enrich existing TEI documents. Just select a text passage, click on a button and within seconds — and without a pointy bracket in sight! — mark it as one of many supported annotation types. A place or person? Sure, and with built-in connectors for external authority files, too. Critical apparatus entries? We got you! Dates, corrections, regularizations and even quick fixes for typos in your transcription.

As usual, everything is customizable and extendable, so if you want a particular kind of annotation we do not support out of the box, it’s not difficult to add your own or tinker existing ones. Read more in the documentation.

The good news doesn’t end there: you can now use the TEI formula element with TeX notation for math. See the component’s demo page which presents some elaborate formulae or visit Publisher’s Demo collection which now sports shiny new examples: Euler’s Algebra for a wee help with your quadratic equations or The Italienische Madrigal by Alfred (not Albert!) Einstein, with musical scores encoded with MEI. It is nicely rendered with Verovio library through a dedicated pb-mei component and you can even listen to the piece to cheer up. And you can now set Publisher’s interface even to simplified or traditional Chinese.

TEI Publisher 7.1.0 is available as an application package on top of the eXist XML Database. Install it into a recent eXist (5.0.0 or newer) by going to the dashboard and selecting TEI Publisher from the package manager.

For more information refer to the documentation or visit the homepage to play around with it.

It’s not for the first time that our special thanks go to the Office of the Historian of the United States Department of State – this time for funding the major portion of the annotation editor. The Math support has been kindly funded by Bernoulli-Euler Zentrum in Basel.

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.

Background

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:

https://teipublisher.com/exist/apps/tei-publisher/api/document/test%2Fgraves6.xml

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:

https://teipublisher.com/exist/apps/tei-publisher/api/document/test%2Fgraves6.xml/html

or if we prefer a PDF:

https://teipublisher.com/exist/apps/tei-publisher/api/document/test%2Fgraves6.xml/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).

Implementation

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.

TEI Publisher 6

Today the new TEI Publisher 6.0.0 is finally out. This is a major release introducing the refactored and extended component library as well as numerous bugfixes and new features.

All Publisher’s web components are now available as a LitElement library distributed via npm. While invisible to users, this redesign greatly improves modularity and simplifies updates of Publisher-based applications. It also facilitates embedding of Publisher custom components into CMS systems (e.g. Hugo or WordPress) and other application frameworks (like angular, vue or react).

This version also brings extended internationalization and full localization into 19 languages, simplified styling, support for data organization based on subcollections, several new and enhanced components (including one for notated music encoded in MEI), improved ODD editor and major extension and revision of the documentation.

mei
Demo page of the pb-mei component

More information about this release can be found on the TEI Publisher blog.

A 3-part online course on TEI Publisher 6 has been led by Wolfgang Meier in June 2020. Video recordings of all the sessions, and a walk-through for the assignments are available for self-study.

Our special thanks for supporting this release go to:

  • Numerous community members who helped to translate and proofread language files via Crowdin
  • Swiss Nationale Infrastruktur für Editionen – Infrastructure nationale pour les éditions for funding a large part of work on the web component refactoring.
  • ACE – Austrian Corpora and Editions of the Österreichische Akademie der Wissenschaften for a small grant to enhance toggling mechanisms