# Reference Manual
In-depth documentation of features like TEI Processing Model, HTML templating, themes and layout etc.
# Introduction
[TL;DR](tldr.xml): shortcut for the impatient reader
[Quickstart](quickstart.xml): gentle introduction for the beginner
TEI Publisher reference manual covers various aspects and technical layers of creation, customization and maintenance of publications based on data encoded primarily in XML. In particular, but not exclusively, we will be discussing _scholarly_ publications based on data encoded in TEI.
This introductory chapter provides a gentle overview of motivations and rationale behind Jinks and TEI Publisher design. For hands-on, technical discussion of particular topics, skip directly to the relevant chapters.
Bridging the gap between a computer-processable representation of sources and tangible, published edition is not a trivial step. It involves precise analysis and modeling, tedious work, and careful orchestration across multiple layers of the technological stack. From the raw data, to the publication - be it an online website or a printed volume - there are many ways to approach the challenge from the technical perspective. For the scholars and content curators, the challenge is rather seen as an obstacle: lengthy, cumbersome and risk-laden but unavoidable process.
_XML data transformed to output with TEI Publisher_
It's not easy to find a way to reconcile the variety and allow for the flexibility within a shared, standards-based framework. From afar, there are significant overlaps between all scholarly publications. Yet the closer we look, the more we notice differences, from subtle to quite fundamental. After all, where is the common ground between a collection of Renaissance correspondence, Buddhist inscriptions, anthology of inaugural poems, and a lexicon of ancient individuals, of whom we only know a few words from their tombstones? Is there a way to accommodate the needs and wishes of editors, at the same time taking into account the technical and economic sustainability, as well as future re-use and interoperability of the scholarly datasets?
The motivation behind TEI Publisher was to provide a tool which enables scholars and editors to publish their materials without becoming programmers, but also does not force them into a one-size-fits-all framework. The solution is based on several foundational principles:
divide and conquer
+ Split complex problems into smaller tasks. This is reflected in modular design at all levels.
do not reinvent the wheel
+ Interface with existing systems and libraries where solutions already exist.
standardize where you can
+ Based on open standards: from well-documented XML vocabularies (like TEI, JATS, DocBook) and formats (JSON) for the representation of data, to support for widely used protocols and specifications (e.g. Open API Specification, IIIF, DTS).
customize where you must
+ Never force a concrete solution: all elements are designed as customizable.
community-driven
+ TEI Publisher framework features and components are a response to real needs of user community: developed to provide a generalized solution to a repeated practical requirement.
open source
+ All components are released under open licenses, assuring that all work continues to benefit the entire community.
## Jinks: edition in few clicks
With the [Jinks](quickstart.xml?id=intro-jinks#intro-jinks) application manager, the core TEI Publisher idea of assembling an edition from the modular "lego" blocks is taken to the next level. The core of TEI Publisher is now decomposed into a set of small, modular profiles, which can be combined and configured to assemble concrete applications. Each profile provides end-to-end implementation for a particular aspect of a digital edition, e.g. support for a certain input format, integration of facsimile images, timelines or map display. Check the [hands-on tutorial](quickstart.xml?id=using-jinks#using-jinks) for a walk through.
Using Jinks is very simple on the surface, nevertheless it operates over the complex, heterogeneous spectrum of conceivable scholarly projects. Therefore it still requires from the user the usual intellectual and scholarly rigour to assure the end result matches the expectations. Similarly, to customize or create a new feature profile, the understanding of the orchestration across the technical layers is necessary.
# Data
Applications generated by Jinks/TEI Publisher will refer to a data collection, where XML files are expected to be stored. A default exists, placing this collection within the application package, to make the prototyping fast and smooth, nevertheless the setting can be easily changed in the config.json configuration file.
Separating your data from application code has many benefits, particularly for actively developed applications and larger data sets. This way the application code can be modified and deployed without redeploying and reindexing the data, and vice versa. It is also easier to maintain separate repositories (e.g. in Git) and differentiate access and privileges for editorial and development teams.
As a rule of thumb it is recommended to separate data and code, nevertheless some projects may prefer to keep their data and application integrated in a single package for the sake of marginally easier distribution.
A series of configuration properties within the `defaults` section determines where data is expected to be available:
`data`
+ specifies the location of the entire data collection. It can be an absolute (starting with the database root) or a relative path (specified in relation to the application collection). By default this is set to `data` subcollection of the application package.
`data-default`
+ Typically, the digital publication contains not only the primary dataset, for example the edited documents collection, but also a number of auxiliary resources: editorial introduction, bibliography, registers of places and people, as well as other ancilliary material. These complementary resources usually, should not appear in the document list the user is presented when browsing the main dataset. The `data-default` property exists to define the entry point to the edition, i.e. specify the subcollection which users should see. If such distinction is not necessary, this property can be set to the empty string.
`register-root`
+ Relative or absolute path pointing to the collection containing register data (entity lists) for people, places etc. If relative it will be resolved relative to `data`.
`data-exclude`
+ An array of XPath expressions pointing to documents to be filtered out when browsing documents. Use this to hide certain documents in browsable collections.
Example: the _Serafin Correspondence_ blueprint comes with three subcollections under data: auxiliary contains a general project description, letters hosts the actual letters, and registers contains entity lists (as the _Entity Registers_ profile expects). Obviously users should only see the letters when browsing documents. Therefore, `data-default` is set to `letters` in config.json.
## Creating a data package
Keeping data and application code together is fine for initial prototyping. However, as mentioned before, it is highly recommended to separate the data from the application code.
From the database and development workflow perspective, separating data and application means that you maintain a dedicated data repository, distributed as a xar package for eXist-db and stored in a particular collection. This collection will be referenced by your application. Just like the application package, the data package can be downloaded, distributed and installed into another eXist-db.
To create a data package, start a new app configuration in Jinks, fill out the abbreviation and the other two required form fields, and in the Profiles tab, select Data Package as the base profile. Click on Apply and wait for the package to be created. Next, use the Files tab to add your data into its pregenerated data subcollection.
After preparing your data package, you'll have to configure your application to use it. Open the main application in Jinks and change the `data` property (and `data-default` if necessary) to use an absolute path pointing to the location of the data within the data package. For example:
```json
{ … "defaults": { "data": "/db/apps/barth-data/data", "data-default": "" }, … }
```
## Hierarchical data collections
Many editions will simply present a flat list of documents, e.g. a collection of letters, monographs or plays. The structure of the data is therefore very simple, all the files are stored on the same level in the `data-default` collection.
Other publications, particularly those including heterogeneous material may require a more complex organization. The _TEI Publisher Documentation and Demo_ app is a good example – its data is further divided into a number of subcollections, containing the documentation, demo documents, JATS and DOCX samples etc. This is reflected in the user interface: the browsing view at the top level shows several panels and users can navigate to the corresponding subcollections by clicking on them.
In general, TEI Publisher applies the following rules for the browse page:
1. if the collection to display contains a collection.html document, this file will be displayed
2. otherwise, TEI Publisher compiles a paginated list of all documents stored in the collection directly and in any subcollections, no matter how deep they are nested
For example, the TEI Publisher Documentation and Demo adds a collection.html to the data root.
collection.html may contain an arbitrary HTML fragment (well-formed XML!) and may include template expressions. However, navigating to a collection is handled by Javascript, so links to subcollections require that a data-collection attribute is present, containing the relative link to the collection.
For example, let's assume a hypothetical application with two main collections: prints and manuscripts. It may include the following collection.html:
```html
```
resulting in the following display:
_Fragment of the subcollections landing page_
## Processing instructions
The default view for a specific document can be configured via a processing instruction. Before displaying a document, TEI publisher will check if a processing instruction exists at the start of the document, telling it which ODD and view template to use (along with other configuration parameters). For example, the following processing instruction associates the document with the view template translation.html, the ODD dantiscus.odd, and switches to a page-by-page display (along TEI page break boundaries):
```xml
```
When viewing the document by structural divisions, two additional settings control the amount of content displayed at a time:
```xml
```
odd
+ The ODD file to use for rendering the document.
template
+ The HTML view template to use. Default is `view.html` as configured in modules/config.xqm.
view
+ Default view to show when browsing the document. Supported values are div, page or single :
1. div : displays one structural division (TEI div, DocBook section …) at a time
2. page : displays the document page by page. This requires page break indicators to be present ( in TEI, not supported for DocBook).
3. single : the entire document (or a selected fragment of it) is displayed at once
depth
+ When viewing entire divisions, the software tries to determine if it should show child divisions in separate pages or include them with the current div. indicates the nesting level up to which divisions should be shown separately. So setting it to "2" will result in divisions on level 3 or greater to be shown together with their enclosing div.
fill
+ If child divisions appear on separate pages, it may happen that the enclosing div contains just a heading or a single line of text. In this case, the algorithm will try to fill the page by showing the first child division as well. The paramter defines the number of elements which should at least be present on a page. If not, the software tries to fill it up.
media
+ A space separated list of output media types supported for this document. TEI Publisher 8 uses this information to limit the download options shown to the user. The output type `web` is always assumed to work and does not need to be specified. Other supported output media types are:
+ epub
+ print
+ fo
+ latex
For example, this documentation uses the following settings in its processing instruction:
```xml
media="latex print fo epub"
```
# Development Workflows
This chapter discusses the different ways to interact with the database while you are developing your own digital edition. In essence, one can distinguish two basic approaches:
1. development is primarily done inside the database using tools like eXide, Jinks or oXygen
2. main development takes place in a local directory using whatever editor and tools you prefer
In reality, you will likely mix both. For example, even if you are mainly working in a directory, you may still want to use the visual ODD editor, occasionally update the application with Jinks etc. You therefore need ways to sync from database to file system and the other way around.
But whichever way you choose, it is important to always have an up to data backup in a safe place in case anything goes wrong. The best way to achieve this is to use a versioning system like git. We strongly recommend to set up a git repository whenever you start work on a digital edition. For beginners, a graphical git client like [GitHub Desktop](https://github.com/apps/desktop) might be the best choice.
## Approach 1: Developing inside the Database
This will be the easier approach as it does not require additional tooling (except for git – see below). It will work perfectly fine if:
+ you are mainly interested in changing the presentation of the data via ODD and TEI Processing Model
+ your application can rely on the existing profiles and requires only minor customization by changing the configuration in Jinks
+ you do not need (or only very little) custom CSS, javascript or additional API endpoints
If those conditions apply, you will mostly work with the visual ODD editor (for addressing the presentation) and Jinks for theming and other configuration changes. If you have to add single source files (like CSS styles), eXide provides a reliable editor.
However, it is vital to keep an up to date copy of your application somewhere save. Jinks itself provides two actions for retrieving a copy (see the bottom toolbar):
Download
+ Packages the application into a single archive (a so called XAR), which you can later re-install into eXist-db using the Package Manager in the Dashboard. This is a quick choice to get a fully functional copy or for passing the application on to other people to try out.
Sync
+ Synchronizes the file hierarchy into a local disk directory. Note that _local_ means the machine where eXist-db is running. If you are using docker, the directory will be _inside_ the docker image. If you connect to a remote server, it will be a directory on the server. Sync therefore is particularly convenient to use during development, to create snapshots to be committed to the source control repository, like Git.
Because Sync won't work for everyone, let's start with the Download option: running the action will result in a file ending with .xar being downloaded to your browser. This is a normal ZIP archive and you can use standard utilities to extract the files into a directory of your choice. If your system does not recognize the .xar as a ZIP and refuses to process it, simply change the file ending.
Contrary to an ordinary ZIP file, a .xar has a standardized internal structure and comes with metadata, which informs eXist-db about how to install the data, create indexes and so on.
The extracted archive contains everything, which would be required to restore the current state of the application. At this point, we strongly recommend to initialize this directory as a git repository and push it to a service like Github.
You can also rebuild the .xar – e.g. after making local changes to files – using the build scripts included in the archive. The build step will result in another, updated .xar being written into the build subdirectory and you can install this new archive into any _eXist-db_ using the _dashboard_ (or command line utility like _xst_, see below).
## Approach 2: Developing in a local directory
If an application reaches a certain complexity, you may prefer to switch to a directory-first approach. This is also how TEI Publisher itself is developed. The advantages:
+ you have a safe copy of your work in a local directory at any point
+ you can immediately commit changes to git or undo them later if needed
+ you can use any tools you like, including the editor of your choice
If you make your changes in a directory first, you obviously have to synchronize them to the database. The easiest way to do so is to rebuild the .xar every time and install it via the _dashboard_. However, reinstalling the entire application may take a while and therefore slow you down.
You can also upload single files using eXide, the file browser in jinks or oXygen's eXist-db integration. But again, this is a manual process.
Therefore, most TEI Publisher developers prefer using a development environment (IDE) like Visual Studio Code, Cursor or Antigravity. They all allow you to install an [eXist-db extension](https://open-vsx.org/extension/eXist-db/existdb-vscode), which – apart from providing XQuery language support – comes with a helpful synchronization utility. Applications generated by Jinks already contain the necessary configuration (in file .existdb.json) to run this synchronization utility.
_Cursor editor with active sync task in bottom panel_
Once activated, the sync utility will continously watch for changes in the monitored directories and synchronize them to the database.
While convenient, there are some caveats of this approach:
+ if you use the visual ODD editor, you need to download the modified ODD yourself as it only exists in the database
+ if you modify the application configuration in jinks and apply it, there will likely be changes to files in the database, but not in your local directory
In those cases, use either the Sync action to automatically sync from database to local directory, or download a fresh .xar and unpack it manually.
Note, however, that if you have the sync task running in your editor, replaced files will be again written into the database. While this does usually not cause much damage, it is better to stop the task temporarily.
## Building
To build an application, you at least need to have [Java](installation.xml?id=java) and the build tool [Apache Ant](https://ant.apache.org/). Both should be installed so they are found in your environment if you open a terminal or shell. Typing `ant` should produce output similar to the following:
```
Buildfile: /Users/wolfgang/Downloads/serafin/build.xml clean: release.true: release.false: [echo] Not a release, moving on ... check-release: git.revision: prepare: [mkdir] Created dir: /Users/wolfgang/Downloads/serafin/build/tp-serafin-1.0.0 [copy] Copying 245 files to /Users/wolfgang/Downloads/serafin/build/tp-serafin-1.0.0 xar: [zip] Building zip: /Users/wolfgang/Downloads/serafin/build/tp-serafin-1.0.0.xar all: BUILD SUCCESSFUL Total time: 0 seconds
```
Expert: if you would like to run the test suite or provide a [local copy of TEI Publisher's webcomponents](web-components-loading), you'll also need to have [nodejs](https://nodejs.org/en) with the `npm` command available in your terminal.
## Useful Resources
Here are links to some of the utilities mentioned above:
[xst](https://github.com/eXist-db/xst)
+ A command line interface to eXist-db, which allows you to install/remove .xar packages, browse collections, upload single files and more.
[jinks-cli](https://www.npmjs.com/package/@teipublisher/jinks-cli)
+ Control Jinks from the command line: supports creating/updating applications from profiles, running actions etc.
[eXist-db VSCode Extension](https://open-vsx.org/extension/eXist-db/existdb-vscode)
+ Adds XQuery language support and a sync task to Visual Studio Code and other IDEs derived from it
[GitHub Desktop](https://github.com/apps/desktop)
+ A graphical client to create and manage git repositories
# TEI Processing Model
TEI Publisher derives its name from TEI and the TEI Processing Model (TEI PM). TEI Processing Model is a part of the standard TEI vocabulary and TEI ODD specification format. It is described in the [Documentation Elements](https://tei-c.org/release/doc/tei-p5-doc/en/html/TD.html#TDPMPM) chapter of the TEI P5 Guidelines. Here we discuss it at length from a practical perspective, including TEI Publisher specific extensions and edge case examples. For hands-on introduction to this topic you may want to follow the [Quickstart](quickstart.xml?id=pm-tutorial) tutorial.
TEI Processing Model specification uses TEI ODD syntax to define how an XML document should be transformed. TEI ODD (short for One Document Does it All) was originally designed to provide formal, machine actionable documentation of the project in the TEI language itself. Processing models in the ODD add a powerful mechanism, through which you can control the transformation of the source XML documents to all output formats: HTML, ePUB, PDF etc.
The processing model approach is flexible and media-agnostic: behaviours and rendition styles are transparently translated into different output media types. A single ODD can handle a multitude of heterogeneous source documents and various output media types with very little adjustment.
_TEI PM based transformation workflow_
## TEI Processing Model transformations
TEI Processing Model allows us to express even **very complex** requirements for processing, including the **distinctions in processing** based on the **document and application context**. For each of the markup tags we need a specific handling, we must only provide an `elementSpec` with one or more nested `model` specifications.
The code fragment below shows `elementSpec` definitions and `model`s that TEI Publisher uses for a few TEI elements: `ab`, `add` and `app`.
_Example of TEI PM syntax_
### Models, behaviours and renditions
Every `model` must specify a `behaviour`, which often is one of the most common: `inline`, `block`, `alternate`, `link` or `note`. Many of the behaviour names are easily understandable, referring to basic web typesetting concepts: `link`, `block`, `heading` or `inline`. Others, e.g. `pass-through` or `webcomponent`, may require a word of explanation. [TEI Guidelines](https://tei-c.org/release/doc/tei-p5-doc/en/html/TD.html#TDPMPM) provide a list of suggested behaviours. TEI Publisher allows users to add their own custom behaviours, either within the ODD itself or by writing XQuery code.
Behaviours define what kind of transformation is expected for the given input. In this sense, behaviours are functions and they may accept a range of parameters, depending on the function in question. For example, the `link` behaviour needs at least two parameters specifying how the URL for the link should be constructed and what the visible link text should be.
Behaviours, as abstract concepts, remain media agnostic. Their implementations in the TEI Processing Model library handle the mapping of the concept to the concrete output format, e.g. HTML or print. `inline` or `note` behaviours hardly differ across media, but obviously we cannot have hyperlinks on printed page, therefore `link` behaviour needs to be adjusted for print outputs.
Even with `behaviour`s, we still lack a way to describe the required formatting for our model, for example to declare that phrases marked as deleted should be rendered with a strike-through, titles should be italicized and lacunae marked with `[...]`. The CSS standard is extremely well suited to express such editorial decisions, therefore TEI Guideline specification highly recommends using CSS definitions for this purpose and TEI Publisher strictly _requires_ it. Follow to output styling section for details.
Please note that any electronic publication needs a general CSS design, regarding layout and styling of its user interface components. Such concerns should be separated as much as possible from the specifications of the processing models. TEI Publisher provides recommendations how to handle these aspects in custom CSS styling chapter.
Illustration below shows, how the same `inline behaviour` can be used to process elements that are semantically very different. Just by adjusting the `content` parameter and specifying the required rendition in CSS the editorial intention for processing can be easily and clearly expressed.
CSS specification for each `model` can be provided directly, via nested `outputRendition`, or, better, indirectly, setting the `cssClass` on the `model` and placing actual CSS rules in a separate file.
_Examples of inline behaviour_
### Context-differentiated models
As mentioned above, processing models are defined first and foremost at the level of an individual markup element (XML tag). Requirements for the transformation are often relatively simple, for example, virtually all TEI-based editions will render `p` elements as paragraphs and `foreign` phrases as inline elements. `unclear` will be often followed by a `(?)` and `sic` by `(!)`. For substantial majority of TEI, DocBook and JATS elements a single model suffices to process it.
On the other hand, a much smaller, but significant, number, particularly for TEI tags, require variant handling. It may be depending on the project conventions, the context in which the element appears in the source XML structure, and also the application context it is presented in. Let's illustrate these three situations with examples.
Community convention
+ Words or phrases supplied by the editor where they are illegible or erroneously omitted in the source are encoded in TEI by `supplied` tag. Typical rendition of this phenomenon uses square brackets `[]` to mark the supplied phrase, while the dominant convention in Polish textual scholarship calls for angle brackets `<>`. Similar differences can be observed in typesetting conventions for expansion of abbreviations, marking of lacunae etc.
XML context
+ TEI element `title` may be used in various locations in the TEI file. It is often used in the transcription, where any kind of work might have been mentioned in the source text. `title` may also occur in various metadata sections, from bibliography to the title of the TEI file itself. Depending on the context, it will be presented differently: the title of the entire TEI document will often be rendered as top-level heading, while one of the titles mentioned in the transcribed documents will typically become just an italicized inline phrase.
Application context
+ The same source fragment may require different handling depending what is the purpose of the presentation. Let's assume that in our source document we have heavily encoded section heading (`head`), which includes a reference to a person (`persName`), but due to the damage to the manuscript witness, it is not fully legible. Nevertheless, the name can be easily reconstructed (`supplied`) based on other evidence available to the editor, who duly provides an explanatory note about the reconstruction process (`note`).
In the reading view of the edition, we want all the encoded information available to the reader, with the conjecture marked with brackets according to the convention, editorial note signaled with a note anchor in superscript and provided as a footnote, and possibly additional information about the identification of the person accessible as a tooltip or margin note.
On the other hand, for the table of contents, all the above would be just an irritating distraction, and in this scenario we want simply the plain, reading content of the heading.
Illustration below depicts a case where requirements for the _reading_ view are drastically different from the _table of content_: the former including extensive critical apparatus and commentary, as well as some information about the layout of the primary source, while table of content focuses on chapter number with supplementary information regarding the range of paragraphs belonging to it. Chapter heading in this case is only available as a tooltip and rendered without any scholarly apparatus.
_Processing requirements differing in various application contexts_
Example above originates from the [Canoniser les Sept Sages](https://www.unige.ch/c7s/) project.
## Processing Model Syntax
TEI Guidelines introduced a small number of new elements for the TEI Processing Model: `model`, `modelSequence`, `modelGrp`, `param` and `outputRendition`. It also extended the content model of `elementSpec` to allow to nest processing models in it. In practice, we need just the small number of elements below to fully express intended transformation for any XML document:
`model`
+ describes the processing intended for a specified element
`param`
+ provides a parameter for a model behaviour by supplying its name and value
`modelSequence`
+ any sequence of `model` or nested `modelSequence` elements which is to be processed as a sequence, not mutually exclusive alternatives
`outputRendition`
+ describes the intended appearance for the model behaviour's output
`pb:template`*
+ code template replacing the default `content` parameter accepted by all behaviours
`pb:behaviour`*
+ custom behaviour definition
Asterisks (*) mark TEI Publisher extensions to the TEI Processing Model syntax. These elements are therefore not in the TEI namespace, but the TEI Publisher namespace, denoted with the `pb:` prefix.
### element
element is primarily used to document the intended processing for a given element. One or more of these elements may appear directly within an element specification to define the processing anticipated for that element. Where multiple elements appear, they are understood to document mutually exclusive processing scenarios, possibly for different outputs or applicable in different contexts.
A processing model defines on an abstract level how a given element may be transformed to produce one or more outputs. The model is expressed in terms of **behaviours** and their parameters, using high-level formatting concepts, such as block, inline, note or heading. A processing model is thus a template description, used to generate the code needed by the publishing application to process the source document into required output.
The example below depicts a situation where a single model is defined for the element. As no @predicate or @output are specified, this model applies for all contexts in which may appear and all possible outputs. Thus all elements will be transformed into inline chunks of text containing only contents of 's child and omitting any possible children.
```xml
```
Processing model for `app` presented above would be most likely insufficient for a scholarly publication. For practical examples consult the TEI Publisher ODD and custom ODD files available in TEI Publisher Documentation & Demo.
### children and attributes
+ @predicate : the condition under which this model applies, given as an XPath Predicate Expression
+ @behaviour : names the function which this processing model uses in order to produce output; possible values include: alternate, block, figure, heading, inline, link, list, note, paragraph
+ @cssClass : one or more CSS class names which should be added to the resulting output element where applicable
+ @output : identifier of the output for which this model applies; applies to all output if no @output is present on a
+ @useSourceRendition : whether to obey any rendition attribute which is present in the source document
+ @pb:mode : processing mode to set to any subsequently called models
+ : allows to pass parameters to @behaviour function; parameters available depend on the behaviour in question; when parameters are not explicitly passed, default values for those are assumed; all behaviour functions use current element as default content
+ : supplies information about the desired output rendition in CSS; its attribute @scope provides a way of defining ‘pseudo-elements’ eg: first-line, first-letter, before, after
NB: this element should be used with care, it is **strongly recommended to use `@cssClass`** wherever possible
### output styling
The intended rendering for the output of a processing model may be controlled in one of the following ways.
+ `model`'s `@cssClass` attribute may be used to specify the name of a CSS style class in an associated CSS stylesheet (read more on specifying CSS styles in the ODD) which is to be applied,
+ the attribute @useSourceRendition may be used to indicate that the rendition defined in the source document should be applied (applicable only to TEI documents using pointers to [CSS rendition schemes](https://tei-c.org/release/doc/tei-p5-doc/en/html/ref-rendition.html)),
+ CSS definition for the default model CSS class (`tei-{ident}`) may be provided
+ element, specifying the styling to be applied in CSS. This option should be used with care, it is strongly recommended to use `@cssClass` wherever possible to separate concerns and avoid redundancy.
It is strongly recommended that use is strictly limited to editorial decisions, such as '_conjectures are to be displayed in square brackets_' or avoided altogether. Under no circumstances it should be used as means to record general typesetting and layout specific design choices. The latter are discussed in the Custom CSS styling chapter.
When more than one of these options is used, they are understood to be combined in accordance with the rules for multiple declaration of the styling language used.
All TEI Processing Model behaviours (except omit and pass-through) add two CSS classes to the generated HTML element: one consisting of the name of the element preceded by the vocabulary prefix (e.g. `tei-div`) and the other additionally suffixed with the number of the model that has been applied (e.g. `tei-div2`). The former allows to specify CSS rules for all the elements belonging to this class. TEI Publisher provides the `tp.css` CSS stylesheet accompanying the default `teipublisher.odd`, with definitions for some of the default CSS classes, for example to ensure default italicization of `hi` elements or titles.
Link to an external CSS stylesheet can be defined in the `encodingDesc/tagsDecl/rendition` section of the ODD. Just specify a relative link in the @source attribute, e.g.:
```xml
```
The file should be stored in the same collection as the source ODD it is referenced from. The linked file should be a standard CSS stylesheet.
When necessary, the processing model library translates the CSS styles into the target media format, e.g. for LaTeX. Restrictions apply due to differences between the output formats. Not all CSS properties are supported for every format. Please refer to the section on Output media settings for further information.
As an alternative to linked CSS files, the element can be used with the @selector attribute to embed CSS rules directly in the ODD.
```xml
font-family: serif; font-weight: 400;
```
Choose one of the two approaches, but do not mix them. In both cases make sure to recompile the ODD after changes as the CSS is merged into the generated code!
### output styling example
Model specifying desired rendition via `cssClass`: contents of elements are to be displayed in italic and wrapped in parentheses:
```xml
```
The ODD file must declare a corresponding CSS stylesheet in `rendition` element in the `encodingDesc` section of the `teiHeader`. In the example below, a file called `tp.css` is expected to contain definitions for CSS classes used in the ODD processing models.
```xml
... ...
```
CSS definitions in the `tp.css` file declared in the ODD example above could be formulated as follows:
```css
.ex { font-style: italic; } .ex::before { content: '('; } .ex::after { content: ')'; }
```
Alternative rendering specification using `outputRendition` is presented below. This method is not recommended, as it leads to verbose and redundant CSS definitions inlined in the ODD. It tends to bloat the ODD and makes it harder to maintain for complex projects, mixing up presentational and functional concerns.
```xml
font-style: italic;content:"(";content:")";
```
### multiple `model`s
As discussed in an earlier section, sometimes several processing models are required for the same element depending on the context.
Set of multiple statements is regarded as **mutually exclusive alternation** and **only the first** model with @predicate **matching** the current context **is applied**.
`model` and `modelSequence` elements are evaluated **top to bottom**, in the TEI ODD document order. The first one for which the `@predicate` condition is satisfied will be applied. Further processing models will not be evaluated at all.
`@predicate` can be specified as any XPath expression which will be evaluated to logically _true_ or _false_. Typically behaviour predicates test one or more of the following characteristics:
the presence or a specific value of element's attribute
+ `predicate="@target"` : true if current element has a `target` attribute
`predicate="@type='chapter'"` : true if current element has a `type` attribute and its value is specifically _chapter_
presence of a child or further descendant
+ `predicate="lem"` : true if current element has a `lem` child element
`predicate="descendant::pb"` : true if current element has a page beginning nested anywhere down the XML tree hierarchy
presence of a specific parent or ancestor
+ `predicate="ancestor::table"` : true if current element is somewhere within a table
`predicate="parent::div"` : true if current element is a direct child of a division
`predicate="parent::div[@type='chapter']"` : true if current element is a direct child of a _chapter_ level division
value of an external parameter passed from the outside*
+ `$parameters?mode=('toc', 'breadcrumb')` : true if the external parameter called `mode` is set to _toc_ or _breadcrumb_
* Convention for referring to, and evaluating, external parameters, is dependant on the processing model engine. _TEI Processing Model library_, used in TEI Publisher, employs the XPath syntax and passes external parameters via `$parameters` map structure.
Predicate tests may use logical operators of conjunction (`and`) or alternative (`or`) to create more complex expressions, following the rules of [XPath expression language](https://www.w3.org/TR/xpath-31/).
### matching `model`s example
For a simple case where single model is insufficient, let's focus on quotes. We may wish to process the element as an inline italic phrase when it appears inside a paragraph (
element), but as an indented block when it appears elsewhere. To achieve this, we need to change the specification for the element to include two elements as follows:
```xml
```
The first processing model will be matched and used only for elements which match the XPath expression given as the value of the @predicate attribute. Other element occurrences will use the second processing model.
Given that quotes are ubiquitous in TEI and may occur in a number of contexts, a more appropriate predicate could test for other contexts than paragraph ancestor, as it happens in the [TEI Publisher ODD](https://github.com/eeditiones/jinks/blob/b6523a09fbbdee6c5141a2d762ff52f11fc27be2/profiles/base10/resources/odd/teipublisher.odd#L616).
###
The element is provided for the case where a sequence of models is to be processed, functioning as a single unit.
As discussed earlier, when multiple `model` elements occur as direct children of the `elementSpec`, they are treated as mutually exclusive and only one of the models will be applied during the transformation.
Nevertheless, sometimes it is necessary to apply two or more behaviour functions to the same source element. Let's consider a verse line, where apart from the content of the line we may want the verse number presented to the side (typically not for each verse, but for every fifth or so).
To achieve this effect, we might want to apply two models in a sequence: first one using the `n` attribute as the `parameter` to produce the ordinal, and a second one, to transform the actual content of the line.
`modelSequence` element is a wrapper that can be used around any group of nested `model` (and `modelSequence`) elements, to ensure that they are all applied. Models are evaluated (checking if predicate tests are satisfied in the current context), and applied in the sequence determined by the ODD document order.
Please note that since predicate rules still apply, therefore in the example below, the first model in the sequence will only be applied for every 5th verse.
```xml
```
`modelSequence` is not the only way to achieve similar effect, depending on the precise requirements, alternative approaches would modify the `content` parameter, or use `pb:template` extension. Particularly to produce nested markup structures the latter method is most useful.
_Numbered verse lines example from [Neolatina Sarmatica](https://neolatina.dhlab.uj.edu.pl/exist/apps/neolatina/s48-1)._
Another use case would be to use modelSequence to generate table of contents preceding the reading text as shown in the example below:
```xml
```
### (processing model group)
The element may be used to group s for better readability of the code, for example elements intended for the same output format.
This element, though present in the specification, has little use in practice and we [do not recommend](https://github.com/TEIC/TEI/issues/2856) its use.
## Behaviours
The [TEI Guidelines](http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-model.html) list a number of suggested behaviours. TEI Publisher implements all these, supplemented with a few _additional_ ones. Users may also add their own custom behaviours, either within the ODD itself, or by implementing custom behaviours in XQuery.
Illustration below shows relative frequency of use of behaviours in the TEI Publisher ODD. `inline` and `block` behaviours are used in more than 50% of models. Close to 10% of models uses `pass-through` behaviour which in majority of cases corresponds with the use of `pb:template` extension.
Several other behaviours are used relatively frequently: `alternate`, `link`, `heading`, `list` and `listItem` as well as `omit`, `webcomponent`, `paragraph` and `break`.
Other behaviours are very closely tied to the specific elements they tend to be solely used for, e.g. `table` and related `row` and `cell` behaviours are used exclusively by their eponymous elements in TEI (and by `table`, `tr`, `td` and `th` elements in DocBook, respectively).
What follows, in ODD customization practice, we'll typically need to use just a handful of most frequent behaviours, therefore it pays off to familiarize yourself with these first.
_Behaviour distribution in TEI Publisher ODD_
### Standard behaviours
This section lists the behaviours supported by TEI Processing Model library out of the box. These include all behaviours suggested by the TEI Guidelines and several additional ones, commonly used in TEI Publisher-based editorial projects.
Behaviour functions accept a range of parameters, depending on the function in question. Where these parameters are not explicitly specified in the , default values are used.
All behaviour functions have at least one parameter called content (with a slight exception of `alternate` behaviour, where equivalent parameter is called default). By default the `content` is set to XPath expression `.`, which means the currently processed node. You may adjust this by explicitly changing the content parameter value in the `model`.
In the parameter lists below we skip the content parameter as it is available for every behaviour. Optional parameters are marked as _optional_ in parentheses, followed by the output mode they apply to, if relevant.
alternate
+ Present _default_ and _alternative_ content. The concrete implementation depends on the output format. Typical web-oriented implementation relies on using a dynamic tooltip to display the alternate content.
| Parameter | Description |
| ---|--- |
| default | the content to display by default |
| ---|--- |
| alternate | alternate content |
| persistent | (optional, web) show a persistent popup on click instead of a tooltip on hover if parameter evaluates to an effective boolean value of true |
anchor
+ Create an anchor to which you can link, identified by the given id.
| Parameter | Description |
| ---|--- |
| id | the id |
| ---|--- |
block
+ Create a block structure, usually a div in HTML or fo:block in fo.
body
+ Create the body of a document. In HTML this will result in a tag.
break
+ Create a line, column, or page break according to type.
| Parameter | Description |
| ---|--- |
| type | e.g. "page", "column", "line" |
| ---|--- |
| label | e.g. "p. 13v" |
cell
+ Create a table cell. If the @cols or @rows attribute is specified, the cell may span several columns/rows.
cit
+ Show a citation, with an indication of the source.
| Parameter | Description |
| ---|--- |
| source | the citation source |
| ---|--- |
document
+ Create output document wrapper. The concrete implementation depends heavily on the output format. For example, in the case of LaTeX output this behaviour sets the document preamble, where options for the paper size, document layout, packages used and so on can be defined.
figure
+ Make a figure with provided title argument as caption.
| Parameter | Description |
| ---|--- |
| title | a caption |
| ---|--- |
graphic
+ Display the graphic retrieved from the given url.
| Parameter | Description |
| ---|--- |
| url | the url to load the graphic from |
| ---|--- |
| width | the width of the graphic, e.g. "300px", "50%" ... |
| height | the height of the graphic, e.g. "300px", "50%" ... |
| scale | a scaling factor to apply. If specified, width and height will be output as percentage based on the scaling factor, which should be a number between 0 and 1. |
| title | a title for the graphics element. Usually not shown directly. |
heading
+ Create a heading.
| Parameter | Description |
| ---|--- |
| level | the structural level of this heading. In HTML mode, this translates to
,
etc. |
| ---|--- |
inline
+ Output an inline element.
link
+ Create a hyperlink.
| Parameter | Description |
| ---|--- |
| uri | the link url |
| ---|--- |
| target | identifier of the tab to open the link in (only web output) |
list
+ Create an ordered or unordered list, depending on the type attribute (e.g. type="ordered"). If a label is present before each item, a description list is output instead, using the label as definition term.
| Parameter | Description |
| ---|--- |
| type | The type of list: use "ordered" for an enumerated list, or "custom" to specify item labels in combination with the n parameter on each `listItem`. The default is "unordered" for a list of bullet points. |
| ---|--- |
listItem
+ Output an item in a list.
| Parameter | Description |
| ---|--- |
| n | a label to use for the item |
| ---|--- |
metadata
+ Output a metadata section, e.g. a in HTML.
note
+ create a note, often out of line, depending on the value of `place` ; could be "margin", "footnote", "endnote", "inline"
| Parameter | Description |
| ---|--- |
| place | defines the placement of the note, e.g. "margin", "footnote" ... |
| ---|--- |
| label | the label to use for the footnote reference, usually a number. |
omit
+ Do nothing: skip this element, do not process children.
paragraph
+ Create a paragraph.
pass-through
+ Process the content without creating any kind of wrapper. Most often used together with `pb:template` to create more complex output markup or just with `content` parameter, to limit processing to selected content. The latter can be also used to specify arbitrary order for processing source fragments.
row
+ Create a table row.
section
+ Create a new section in the output document. In HTML mode, this translates to a element being output.
table
+ Create a table.
text
+ Output literal text.
title
+ Output the document title. In HTML mode, this creates a element. In LaTeX, it adds the title to the document metadata.
webcomponent (TEI Publisher extension)
+ Output a custom HTML element using the value of parameter name as the custom tag name. All other parameters are translated into corresponding attributes (properties of the webcomponent).
| Parameter | Description |
| ---|--- |
| name | the tag name to use for the custom element. Must be a string value. |
| ---|--- |
### Custom behaviours in the ODD
The two dozen behaviours supported by TEI Processing Model library out of the box are enough to cover most standard tasks, but sometimes a custom behaviour may make the ODD code clearer and easier to maintain.
By combining code templates with parameters we can create a very simple mechanism to define new behaviours right inside the ODD!
Take the TEI Publisher documentation as an example: it is written in Docbook 5 and transformed via ODD. The documentation includes some videos which are hosted on youtube. In DocBook these are represented by <videodata> elements inside a <videoobject>.
```
<figure xml:id="edit-odd"> <title>Screencast
```
In the HTML output we would need to transform this into an
```
#### Note
Note how we have to reset the namespace on the ? This is required because the default namespace in an ODD document is the TEI namespace. You therefore need to reset it whenever you want to output elements in another or no namespace inside a template. Without this, the `iframe` would end up in the TEI namespace. Web browsers will usually ignore it, but it would be incorrect nevertheless.
All behaviours should be defined in the TEI header of the ODD file (or – to be exact – the < tagsDecl> part of the ). You may create multiple behaviour declarations with the same @ident, provided that they apply to different @output modes. Parameters declared via without @value attribute are expected to be passed to the behaviour from the calling model. A parameter may be empty though. If you define an XPath expression as @value attribute, the result of the XPath evaluation will be used as value for the parameter.
The new behaviour defined above will be named iframe and takes three parameters: src, width and height. It can now be used by a as follows:
```
```
For further code examples, please have a look at [docbook.odd](odd/docbook.odd), which is used for viewing the documentation.
#### Note
The graphical ODD editor in TEI Publisher does not yet support defining your own behaviours via . You have to make these changes in the source XML using an XML editor. You can, however, use the graphical editor to continue editing the ODD afterwards. It makes sure not to overwrite your hand-written code upon save.
### Custom Behaviours in XQuery
While TEI Publisher does provide ways to create custom behaviours in XQuery this should only be used when well justified: custom XQuery behaviours limit the portability of the ODD and negatively influence maintenance. It is recommended to rely on standard behaviours, and extensions of the ODD syntax wherever possible.
Avoiding custom behaviours works quite well for HTML output, nevertheless edge cases exist where creating custom behaviours in XQuery makes sense. Follow instructions from the XQuery extension modules chapter for this approach.
Avoiding custom behaviours works quite well for HTML output and we have realized complex projects with no extension behaviours. Things may become more difficult for LaTeX output: there are hundreds of packages to use, and users typically define their own macros or environments for all recurring typesetting tasks. For example, to print a TEI , experienced LaTeX users would normally create a corresponding `\persName` macro and handle the formatting details there. Similarly, processing highly specific XML sources, for example to produce the reference pages for the TEI Guidelines themselves, is best handled via custom XQuery behaviours.
## Custom markup templates with
The standard supported behaviours are sufficient to cover most typical tasks, but more complex HTML markup or procedural output formats like LaTeX require more customization and control over the generated output. The TEI Publisher library therefore extends the processing model syntax with a custom element for defining code templates. The `pb:template` element belongs to TEI Publisher, not TEI namespace ( http://teipublisher.com/1.0).
Within the ODD, a may define a element containing a code template. The template is expanded first, and the result is passed to the behaviour specified for the model, in place of the content parameter accepted by all behaviours. The very simple case of outputting a in LaTeX could therefore be written as:
```xml
\persName{[[content]]}
```
The template can reference other parameters defined within the by enclosing the parameter name in double brackets. In the example above we're referencing the default parameter content, which does not need to be explicitly specified. Here it therefore retains its default value, which in this situation is the content of the tag. The parameter will be processed in a normal way before it is passed into the template, so if contains any nested TEI markup, the matching processing models will be applied first.
The result of expanding the template is then passed to the behaviour ( `inline` in the example above).
You may also specify additional parameters to be included in the template. For example, the TEI document may contain a glossary of terms which are referenced in the text using `text`. In LaTeX this would translate to `\glslink{ref}{text}`, which can be easily produced by the following :
```xml
\glslink{[[ref]]}{[[content]]}
```
We define an additional parameter ref, which contains the id string from the @ref attribute, stripping out the leading '#'.
The templating mechanism is not limited to LaTeX, but may be used to generate HTML or FO markup, for example, if you have to generate a complex, nested HTML fragment for a single TEI element. This is difficult, and sometimes impossible, to achieve without templates.
The following example uses the pb-popover webcomponent to display the `tei:persName` from a person register for a given `tei:persName/@key` of your TEI document.
```xml
[[content]][[person-from-register]]
```
## XQuery extension modules
Where possible, developers should stick to the standard behaviours, or use the and extensions of the ODD syntax. However, there might be situations in which it is necessary to generate a specific type of complex output, which requires the full power of XQuery. To facilitate this, the implementation allows extension modules to be configured, with definitions of custom functions and behaviours which may be then used in the ODD.
Configuration is done via an XML file which must reside in the same collection as the source ODD files. It contains a series of
