About the Edition


Editorial principles 4: technical documentation (website creation and design process)

This section gives a fuller technical account of how the edition was designed and implemented, and how text, image, and annotation data are brought together at runtime. It complements the other editorial principles by describing the web architecture, data model, and technologies used. The project data is available at 10.5525/gla.researchdata.2017.


Editorial-to-digital workflow

  1. Editorial preparation of the transcription and translation (with harmonisation of inherited materials from earlier phases of work).
  2. Encoding of the text in TEI-XML, preserving folio boundaries, lineation, additions, deletions, and note structures.
  3. Encoding of scribal attribution through handShift and metadata markers (notably note type="scribe").
  4. Creation and refinement of image-region annotations using IIIF-compatible Web Annotations linked to scribal profile IDs.
  5. Implementation of server-side delivery and transformation logic so that a requested folio can be rendered as linked text, notes, and image.
  6. Iterative quality control across TEI structure, viewer rendering, scribal filters, and search/index behaviour.


Technology stack

  • Database and application runtime: Elemental (native XML database).
  • Server-side logic: XQuery 3.1 modules (routing, folio extraction, JSON endpoints, search).
  • Transformation layer: XSLT 2.0 for TEI-to-HTML rendering.
  • Data encoding standard: TEI-XML for transcription and translation sources.
  • Image interoperability: IIIF (Image API and annotation workflows).
  • Image server endpoint used by the viewer: Cantaloupe.
  • Annotation format: W3C Web Annotation JSON, including SVG selectors for polygon/region targeting.
  • Frontend: HTML/CSS plus JavaScript (including OpenSeadragon for zoomable image delivery and overlays).
  • Search: eXist-db Lucene full-text index and KWIC summarisation.


Custom IIIF annotator used in production

The project includes an ad-hoc customised annotator built specifically for this edition’s scribal workflow. It is not a generic external service: it was implemented to match the manuscript navigation, scribal profile model, and storage format used by the public viewer.

  • The annotator loads a chosen manuscript and folio as IIIF info.json through OpenSeadragon, using the same folio-to-image mapping logic as the reader interface.
  • Editors can create polygon and rectangle regions, switch between draw/select modes, and delete selected annotations.
  • Each region is explicitly assigned to a selected scribal profile code (for example sc024) via the in-page scribe selector.
  • On save, internal regions are serialised into IIIF/W3C Web Annotation JSON: type="Annotation", motivation="tagging", TextualBody with the scribe code, and SvgSelector containing polygon/rect geometry.
  • Write operations are posted to /annotations, which persists manuscript-level AnnotationPages in data/faustina.json and data/julius.json.
  • The save routine is merge-aware: for the current image+scribe pair it replaces that subset, while preserving annotations belonging to other scribes or canvases in the same JSON file.
  • For robustness, the tool includes auto-save and browser local-draft fallback; if server persistence lags, local drafts are retained and reloaded to prevent annotation loss.
  • Those same JSON files are consumed by the public read-only overlay, so editorial annotation and user-facing display use one shared data source.


How a folio request is rendered

  1. A request specifies manuscript/source, language, and folio (for example ?source=faustina&lang=lat&folio=21v).
  2. XQuery resolves the corresponding TEI file and locates the target folio marker (pb/@n).
  3. Only the selected folio fragment is transformed server-side to HTML via XSLT.
  4. The transformed sections are inserted into the viewer layout (main text, margins, notes).
  5. In parallel, the viewer loads the matching IIIF image from the Cantaloupe endpoint.
  6. IIIF/Web Annotation JSON is loaded and SVG-based regions are drawn as filtered scribal overlays.


TEI markup conventions used in this implementation

The edition currently uses this TEI element set: TEI, teiHeader, fileDesc, titleStmt, title, publicationStmt, sourceDesc, text, body, p, pb, lb, hi, add, del, gap, note, handShift, ref, table, row, cell.

Project-specific controlled values currently in use include:

  • add/@place: above, below, left, right, left-vertical, right-vertical, top-left, top-centre, top-right, bottom-left, bottom-centre.
  • hi/@rend: superscript, italic, bold, right-aligned, red, blue.
  • del/@rend: erasure, cancelled.
  • gap/@reason: indent, space, hole.
  • note/@type: including scribe for metadata markers.
  • handShift/@scribe: profile labels such as sc001–sc124, plus scEditor where required.
  • ref/@type="http" for outbound links.


Search and index implementation

Full-text search is implemented through eXist-db’s Lucene integration. The index configuration targets key TEI content nodes (including body, p, add, note, and hi), while range indexes support selected attribute lookups. Query handling is performed in XQuery and snippets are generated with KWIC summary output for context display in results.


Maintenance and sustainability practice

  • Maintain structural synchronisation between Latin and English TEI files at folio level.
  • Extend TEI @place/@rend vocabularies only when corresponding rendering support is added.
  • Keep TEI as the canonical scholarly data layer; treat rendering as a replaceable interface layer.
  • Maintain IIIF/annotation interoperability so image and region data remain reusable beyond the current viewer.

 

Author: Luca Guariento
Last updated: 07/06/2026