# Gentle Introduction to TEI Publisher

Start here. Introduces key concepts and provides a tutorial to help you getting started.

# Introduction

TEI Publisher provides a flexible and sustainable _toolbox_ which enables scholars with limited technical skills to publish their material without forcing it into a one-size-fits-all framework. Our mantra is to stop reinventing the wheel with every new digital project and reuse what others have already built instead. And, most importantly, help to improve the shared base by adding what's missing into the communal pool.

TEI Publisher provides a smooth and fast entry path for editors with little technical experience while remaining endlessly flexible and extensible for advanced users. 

Numerous projects realized with [TEI Publisher worldwide](https://www.e-editiones.org/map/) prove that it is:

1.  a truly universal tool for any kind of digital publication, from scholarly editions to journals, monographs, lexicons, and much more

2.  suitable even for very complex and multi-faceted material

3.  sustainable and future-proof

4.  capable of generating high quality, camera ready material for print publishing

5.  suitable for any XML, not only TEI (this documentation is written in DocBook!)

## Overview

Starting with the version 10, based on Jinks application manager, the core TEI Publisher idea of assembling an edition from the modular _"lego"_ blocks is taken to the next level. Despite the changes to the interface and internal reorganization, advanced users will nevertheless find most underlying concepts and components slightly changed but still recognizable. 

Version 10 substantially extends the _toolbox_ idea of simple, recombinable blocks: the core of TEI Publisher itself 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.

## Assembling an application

An actual application is created by selecting desired features and customizing their configuration. This is achieved through a central configuration file, which can be easily edited through the user interface. Human-readable structure of the configuration file coupled with syntax suggestions in this step greatly simplify the development process.

Profiles may cover individual functional _features_, like the aforementioned timeline but others take care of the _presentational_ aspects, like typesetting and styling. Such profiles are called _themes_.

Profiles may also aggregate and customize each other, so a profile may depend on one or more other profiles. At the top of such a hierarchy sits what we call a _blueprint_, which is essentially a ready-made configuration for a complete application. Usually it will be targeting a specific use case, e.g. a correspondence edition or a dictionary. In the simplest case, a blueprint may be just a configuration file, which tailors the configuration of profiles it uses for the specific purpose of this particular blueprint.

## Continuous development

TEI Publisher comes with a central application manager, Jinks, which manages all profiles and the applications generated from it.

Creation of an application is no longer a one-time generative step, but it can be approached iteratively: new features may be added or removed, configuration for the existing ones modified. The same user interface which allowed us to select, pre-configure and generate our application, can be used to reconfigure and regenerate it at any later point. 

As new profiles are added to the public library - or new versions are released for the existing ones - this application manager can take care of updating profiles and their dependencies used in custom applications under its control. Updates can largely be carried out automatically with the number of necessary manual interventions reduced to a minimum and most updates applied with a single click. Gone are the days when users had to read through update instructions to manually migrate to a new version of TEI Publisher. 

## Basic vocabulary

To clarify how various parts fit together, let us summarize some key concepts, which will be used in the rest of this documentation:

TEI Publisher 
+  denotes the software framework as a whole, i.e. the entire toolbox, comprising all profiles and libraries

Jinks 
+  the central application manager, which generates applications and manages updates

TEI Publisher Documentation and Demo 
+  refers to the application containing this documentation and a selection of demos. It mimics the old monolithic TEI Publisher application, but is now generated from a blueprint.

Profile 
+  a modular building block for a TEI Publisher application. Profiles can extend other profiles and may be combined to create applications. We distinguish several kinds of profiles:

Base 
    +  a special profile, used by all TEI Publisher applications, providing the core server-side API and basic page layout without styling

Feature 
    +  a functional profile to be combined with base and potentially other profiles. It provides all necessary resources to fully implement a specific functional scope, e.g. docker configuration, register sidebar, or a timeline.

Theme 
    +  provides a particular look and feel. It supplies all necessary CSS styles, fonts and graphic assets to achieve that.

Blueprint 
    +  a complete template for an application targeted at a specific use case, e.g. a monograph, correspondence edition, dictionary etc.

TEI Processing Model 
+  the very core of TEI Publisher. Part of the TEI Guidelines and the TEI ODD specification format, it defines how documents are transformed from the source XML into output formats (e.g. HTML, ePub, print).

Webcomponents 
+  library of interactive custom HTML elements. These main user interface building blocks of TEI Publisher can be freely combined to create robust HTML pages with TEI Publisher. Part of the HTML5 standard and natively supported by browsers.

Jinks Templates 
+  a templating language used by Jinks during application generation as well as within profiles to fill placeholders with content.

## e-editiones.org

Since its first incarnation in 2015, TEI Publisher has gained substantial following with numerous academic and commercial projects around the globe, which are relying on it for their editorial and publishing needs. Grass-roots user initiative led in 2020 to the foundation of an international non-profit association [e-editiones.org](https://e-editiones.org) with the focus on further joint development of TEI Publisher, open standards and best practices for digital editions. 

TEI Publisher development is only possible thanks to generous contributions of developers, users and institutions willing to employ Open Source approaches so that the whole community can reuse and benefit from their work.

A growing number of projects from small to large that have decided to publish their materials with TEI Publisher gives us all not only the opportunity but also the responsibility to make the project thrive for years to come and to make it truly sustainable option for XML publishing! Consider joining [e-editiones.org](https://e-editiones.org) through your affiliated institution or individually to support our efforts. 

We invite the community to contribute to the project – by means of code, ideas, documentation, tutorials and funding. 

You don't have to be a developer to contribute, you can do so in a number of ways! 

1.  Check out the source code, modify it, document it, enhance it.

2.  Create new or enhance existing example documents and ODDs so we present showcases for various TEI applications.

3.  Report your issues, feature requests or ideas for discussion via [GitHub issue tracker](https://github.com/eeditiones/tei-publisher-app/issues). 

4.  Discuss with us on [e-editiones slack chat](https://join.slack.com/t/e-editiones/shared_invite/zt-e19jc03q-OFaVni~_lh6emSHen6pswg) or through the [mailing list](https://admin.hostpoint.ch/mailman/listinfo/community_e-editiones.org) and [@EEditiones twitter](https://twitter.com/EEditiones). 

5.  Contribute to translations via [Crowdin](https://crwd.in/tei-publisher). Please contact us if your target language is not listed and you'd like to work on it. 

6.  Port back your customizations (e.g. profiles or themes) to the TEI Publisher code base so that others can use it too (or ask us to do it for you)! 

7.  Help and mentor others – publish teaching materials, answer questions on our Slack channel, mailing list and other forums. 

8.  Sponsor a concrete feature or fund a development grant. 

# Guided Tour

If you are browsing this documentation through the official website or you have installed TEI Publisher via the docker image, you will find four applications on the start page:

If you installed TEI Publisher without docker, you will only see two applications here. You can generate the others yourself though.

![](home-explore.png) 

_Start page showing four installed applications_

Documentation and Demo 
+  Provides the documentation you are reading and a few selected examples

[Correspondence Edition](/exist/apps/tp-serafin) 
+  A more complex example, showcasing a parallel view with transcription and translation, entity register of people and places, correspondence navigation and a timeline.

[Workbench](/exist/apps/tp-workbench) 
+  Tools to help with the edition workflow: a web-based annotation editor and an online editor for working directly on a TEI text.

[Jinks](/exist/apps/jinks) 
+  TEI Publisher's application manager: all other apps were generated by this.

For a first overview we recommend to start with the _TEI Publisher Documentation and Demo_ application. This includes the documentation, provides a few selected demos, and also allows you to upload your own documents to the demo collection as well as to play around with different ODDs or create your own.

The first three apps correspond to one of the pre-configured blueprints available in Jinks. See below for more information on profiles and blueprints.

## Browsing Documents

The start page of _TEI Publisher Documentation and Demo_ serves as an entry point to explore and experiment.

The left side panel presents search and filtering options. The central panel lists the available collections or – if you browse into a collection – the documents within. Another panel to the right shows the list of ODD files provided by the app.

![](start-page-collections.png) 

_First options in the start page collection listing_

The usual starting point is the **Demo Collection** with which users can explore a range of selected use cases, demonstrating various genres, encoding styles and presentation layouts. Various customization aspects are handled using different ODDs and view templates. We suggest to have a look at each of them to see what TEI Publisher can achieve out of the box.

Every example – including the documentation – can also be downloaded in different media formats. Not all formats will be available for every sample. TEI Publisher supports ePub, Markdown and PDF. For the PDF there are three options: using Print CSS, FO or LaTeX as intermediate format. FO and LaTeX are disabled by default. For further information refer to the [reference guide](documentation.xml?id=output-media).

![](download-menu.png) 

## The Document View

The document view can vary, sometimes substantially, depending on the sample document you are looking at. This is a natural consequence of TEI's versatility and broad scope of its application. However, key elements of the user interface intentionally remain the same across examples and applications. This starts with the central toolbar, showing a series of buttons by default:

![](content-toolbar.png) 

_Central toolbar in demo collection_

Select ODD 
+  The Select ODD dropdown allows you to change the currently used ODD. Note that most texts require a particular ODD. However, if you develop your own ODD, this dropdown allows you to quickly switch e.g. between different versions.

Page navigation 
+  Those two buttons allow you to navigate to the next/previous page in a longer text

    Alternatively, you can use the left/right keys on your keyboard!

Content zoom 
+  Controls the font size for the content of the document to improve readability

Recompile ODD 
+  Only available when logged in; this button triggers regenerating the ODD used to display the current document and reloads the page

Some examples may contribute additional buttons (e.g. the Cortés letter).

Depending on the text you may also see one or two sidebars to the left and right of the content area. These can be resized or minimized.

TEI Publisher 10 tries to provide a consistent layout across all applications. See the section on [Layout, Themes and Styling](documentation.xml?id=themes-and-styling) in the reference guide.

## Selected Use Cases

Sample documents which are included in TEI Publisher's installation package do not represent the full scope of its applications. Selection is based on community-provided use cases:

![](demo-collection-overview.png) 

_Browsing Demo collection_

+  _Critik der reinen Vernunft_ from the _Deutsches Textarchiv_ corpus presents a philosophical tractate, originally published in print, thus following 'traditional' book structure with front pages, foreword and chapters. 

+  Shakespeare's _Romeo and Juliet_, from _Bodleian First Folio_ project uses dedicated TEI elements to encode structure of the play but it also showcases the parallel transcription and facsimile alignment for its presentation which is obviously of general application and could be used for any genre, not limited to dramatic texts. 

+  Correspondence corpora are common, yet very interesting, subjects for digital editions. Despite basic similarities in structure, depending on the period, scope and particular research perspective, intended presentation may vary enormously. We are presenting samples of:

    +  A 16th century manuscript letter of **Hernán Cortés** showcasing parallel transcription/translation and facsimile view and transcription enhanced with commentaries and explicitly encoded transcriptional features.

    +  A letter from **Van Gogh** to Paul Gauguin written in 1888. This intentionally reproduces the flexible column layout pioneered by the [Vincent Van Gogh Letters](http://vangoghletters.org) online edition, which is a model example for correspondence.

+  For a taste of completely different encoding style we present several 19th century lexicons and dictionaries:

    +  A manuscript collocative dictionary of Polish **Bogactwa mowy polskiej** featuring interactive highlights for regions of interest of the facsimile when hovering over dictionary headwords. Internal composition is based on the `entryFree` element with a rich microstructure.

    +  An encyclopedia of philosophic terms by Friedrich Kirchner and Carl Michaëlis, published in 1907: _Wörterbuch der Philosophischen Grundbegriffe_. This is based on the Lex-0 customization of TEI and provides a sidebar to browse the available lemmata.

#### Note

You may notice that the list of included samples is more limited than in version 9. Some examples have been moved into separate profiles (see the _Serafin_ blueprint for a correspondence edition), the rest has been condensed and streamlined. The base ODD now covers many more TEI features out of the box, so fewer samples are necessary.

We'd like to stress that preparing showcases above has been only possible thanks to numerous projects releasing their sources openly, in particular the [Bodleian First Folio](http://firstfolio.bodleian.ox.ac.uk), [Deutsches Textarchiv](http://www.deutschestextarchiv.de), [Vincent Van Gogh Museum](http://vangoghletters.org) and [ EEBO-TCP](https://www.textcreationpartnership.org/tcp-eebo). We'd also like to thank William Graves and Anna Skolimowska for sharing their correspondence material. 

All TEI Publisher's sample documents are XML files which are transformed into a HTML webpage for display in the browser. We have already mentioned in the very first section that the TEI Processing Model lies at the heart of the Publisher – the ODD file associated with a document defines the rules of transformation of the XML source file into HTML. An introduction to ODD and the processing model will be given below in the corresponding chapter. A detailed discussion of the Processing Model can be found in the [reference manual](documentation.xml?id=pm-syntax).

For now it is sufficient to say this is where decisions if a TEI element should be rendered inline, with a tooltip, or as a marginal note, are made. Simplifying things a bit, the _text_ of the document that you see rendered in your browser is an effect of applying the rules from ODD file to the source document. When opening a document of the Demo collection, it is possible to see in the URL the odd parameter indicating which ODD file is being used to process the document, e.g. [demo/F-rom.xml?odd=shakespeare](../demo/F-rom.xml?odd=shakespeare).

Most demos come with their own ODD. However, all of them – at least if they deal with TEI – extend the base ODD, teipublisher.odd.

## Uploading documents

You may already have some documents you might want published, whether they are in TEI, DocBook, JATS, MS Word DOCX or other XML format. The _Documentation and Demo_ application allows you to upload documents into the Demo Collection. The first step is to upload them into the database, for which you need to be **logged in**. The user and password are displayed in the information block on top of the right sidebar.

#### Important

If you are reading this on the official TEI Publisher [website](https://tei-publisher.org), you won't be able to log in or upload. Please [install](installation.xml) your own instance of TEI Publisher to experiment with it. The remaining sections of this quickstart guide assume you have TEI Publisher installed yourself.

![](upload.png) 

_The Upload Panel_

Upon successful login, uploading is just a question of dragging your documents onto the Upload area. They will become available in the document list immediately after upload is successfully completed. The upload panel will also display the upload results. In case of problems, very often resulting from not well-formed XML, you will see a warning message.

Now you can view your documents! The transformation will use the rules of the base ODD. For most text-centric TEI, the default rendition should already produce a readable result, but you will likely find aspects to improve to match your expectations. Quite often the need for customization will be limited to just a handful of elements. Refer to the Changing the presentation via ODD chapter to learn about the ODDs and the Processing Model.

If you upload a Microsoft Word document, the upload will automatically trigger the conversion of Word to TEI, using a special ODD for the transformation. Please note that the focus of this conversion is to preserve textual content, structure and basic semantics of the text, not to provide authoritative mapping of complete set of MS Word features to TEI. Refer to [DOCX handling](documentation.xml?id=docx) section for more information.

# Hands-on with Jinks

After playing around with the _TEI Publisher Documentation and Demo_ application, let's try and generate our own custom edition. As explained above, TEI Publisher now has an application manager, called _Jinks_. This will be your main entry point for creating or updating a custom edition.

You can access _Jinks_ via _eXist-db's_ Dashboard. If you have not installed _Jinks_ yet, use the Package Manager in the Dashboard to do so.

Opening Jinks for the first time, you will see a login page. The default user is `tei`  and the password is the one displayed on the _Documentation and Demo_ application browsing page. If you managed to login you see the main administration page  with three columns.

![](jinks-login.png) 

_Jinks Login_

## First Steps

+  The sidebar to the left shows the list of installed applications which were created with Jinks (if any). In the screenshot there are two applications: `tp10` and `barth`. 

+  The central column contains the main configuration form with several tabs. 

+  The right column presents the configuration, as is currently in effect for the application. The configuration is in JSON format and will initially show as an empty object (empty curly brackets). As you fill out the form, you will see how the JSON configuration is populated with corresponding entries.

To start, you must fill at least the top three input fields under the first tab, Application Configuration. In the first box, Abbreviation, provide a short but unique name. In the screenshot the abbreviation is barth. It will serve as a collection name in the database, where the application is stored. 

**NB:**Abbreviation may not contain whitespace, brackets and special characters. It may only contain alphanumeric characters (letters and numbers) supplemented with dashes (-) and underscore (_). 

![](jinks-config.png) 

_Jinks Application Configuration_

After filling out the abbreviation field, suggestions for the following two text boxes are provided automatically. The label is the title of the application, and will be used to caption the app in the Dashboard and elsewhere. It will initially be the set the same as the abbreviation, but you may change it to be more descriptive - and you can freely use whitespace, brackets etc. The unique identifier must be a URI, but it does not need to be a real URL, pointing to some existing website. Like a namespace in XML, it can be anything as long as it is syntactically valid and unique.

Running the generator with just these settings, the result would be an application without any documents. To provide some data to test with, switch to the Profiles tab, search for the Demo Data feature in the Data Packages subsection and enable that checkbox.

![](jinks-profile.png) 

_Jinks Profiles - Demo Data_

You are now ready to run the generator for the first time: click on the Apply button in the bottom toolbar of _Jinks_. you will see a wait indicator appear next to the button. The process may take a while as it consists of multiple steps:

1.  configurations of all selected profiles are merged

2.  files supplied by each profile are copied into a temporary collection in the database

3.  the temporary collection is packaged and installed into eXist-db

Once the application is installed, a dialog will open. If you are creating a new app, it will inform you that the package has been deployed, along with a link which you can click to open the newly created application.

![](jinks-dialog.png) 

_Jinks Dialog_

If you followed this section to the letter, and added only the Demo Data feature, the created application should present three sermons by theologian Karl Barth. Clicking on one of those will display the text of the sermon.

In Jinks itself you can now see your new created application in the left column. 

![](jinks-barth.png) 

_Jinks Profiles Tab_

## Adding Features

The sermons contain mentions of places and people. To make use of the information available about these in the dataset, we can enable the profile dedicated for this purpose.

Switch back to _Jinks_, go to the Profiles tab and find the Entity Registers profile in the Features category. Enable it and click Apply again.

![](jinks-entity-registers.png) 

_Jinks Entity Registers Feature_

The Command Output dialog will now present a list of updated files. Close it and return to the generated app. Looking at the menubar, you will notice that there are new menu items for People and Places, leading to separate pages for browsing those entities.

We might also like to show a list of places and people mentioned in the current document, when viewing one of the sermons. This sub-feature is not enabled by default, because editions may not necessarily want limit it to some pages, or not to use it at all.

To enable it globally, go back to Jinks and look at the editor to the right, which shows you a JSON representation of the currently active configuration for the application. Right now it should look like this (though the order of properties may differ):

```json
{ "pkg": { "abbrev": "barth" }, "label": "barth", "id": "https://e-editiones.org/apps/barth", "extends": [ "base10", "demo-data", "registers", "theme-base10" ] }
```

Configuration parameters for feature profiles must go under a property called `features`, followed by the name of the profile. While we're at it, we could also disable the navigation buttons in the toolbar (the sermons use a single-page display). Change the configuration and add the `features` as below:

```json
{ "pkg": { "abbrev": "barth" }, "label": "barth", "id": "https://e-editiones.org/apps/barth", "extends": [ "base10", "demo-data", "registers", "theme-base10" ], "features": { "register": { "enabled": true }, "toolbar": { "navigation": false } } }
```

After applying the new configuration, you should find a register sidebar, listing people and places, to the right of each sermon's text.

![](jinks-registers.png) 

_Document view with register sidebar_

## Customizing the theme

Some of the most frequently changed styling aspects can be configured via the config.json, allowing users to change colors, fonts or logos without editing CSS. For example, most projects will want to use their own logo in the menu and the splash screen (which appears while a page loads), and perhaps pick a custom background for the header as well.

To make these changes, we first have to upload the necessary images. The Files tab in _Jinks_ provides a simple file manager, which we can use to browse and upload files into the database. It will initially show the collection root of the currently selected application. Images used for the general page layout should go into resources/images, so navigate to that collection, then either drag and drop the desired images from your system's file manager or click the Upload button.

The Files tab will only become visible after you generated the application!

![](jinks-filemanager.png) 

_Jinks: Managing Files_

Either use your own images or the ones from the following sample:[logo-white.png](images/karl-barth/logo-white.png), [type.jpeg](images/karl-barth/type.jpeg) and [Karl_Barth.jpg](images/karl-barth/Karl_Barth.jpg). They are available from [GitHub Jinks repository](https://github.com/eeditiones/jinks/tree/main/profiles/docs/data/doc/images/karl-barth) as well. It is possible to upload multiple resources into a database collection at once. 

![](jinks-upload.png) 

_Jinks: Upload files_

With the images uploaded, we can add them to the configuration. All settings related to the look and feel of an application go into the `"theme"` property of the configuration file. For example, to change the logo, splash screen image and menubar background, we could change the configuration as follows:

```json
{ "pkg": { "abbrev": "barth" }, "label": "barth", "id": "https://e-editiones.org/apps/barth", "extends": [ "base10", "demo-data", "registers", "theme-base10" ], "features": { "register": { "enabled": true }, "toolbar": { "navigation": false } } "theme": { "logo": { "image": "../images/logo-white.png" }, "menubar": { "background-image": "../images/type.jpeg" }, "splash": { "image": "../images/Karl_Barth.jpg" }, "fonts": { "content": { "family": "var(--jinks-base-font-family)", "size": "1.125rem" } } } }
```

Note that all image paths will be relative to the CSS stylesheet (which lives in resources/css), so we have to go up one level (using ../) and then down to images.

The final setting above also changes the font used for the content. By default this will be a serif font (_JunicodeVF_), which is good for many historic scripts, but for a 20th century text, we may prefer to use the same sans-serif font as for the rest of the page (_Inter_). However, instead of providing a font name directly, we reference the CSS variable `--jinks-base-font-family`, which predefines the corresponding font.

We may want to decrease the font size a bit as well, setting it to `1.125rem`. Note that for font scaling to work properly, we should use relative sizes based on the browser's base size, therefore using `rem` here, not sizes in points or pixels.

![](karl-barth-theme.png) 

_App with theme changes applied_

Finally, we can change the color scheme used by switching to the Theming tab and choosing one of the available schemes. Note that this will add a property `"palette"` to the configuration, referencing the selected color scheme's name. 

TEI Publisher comes with a small number of predefined color schemes, but you can add your own palette. Using a well-chosen, limited color palette is in general considered good practice in web design, which is why we avoid using hard-coded colors.

## Creating an ODD

And now: action! One important step is still missing for a custom edition: creating your own ODD for text transformations. Jinks provides a control for this on the Application Configuration tab. Since we're dealing with Karl Barth, let's add an ODD called barth.odd.

![](jinks-create-odd.png) 

_Create your own ODD_

After clicking Add, you will see two new configuration entries:

```json
"odds": [ "barth.odd" ], "defaults": { "odd": "barth.odd" }
```

The first adds barth.odd to the list of available ODDs inherited from the base and other profiles. The second sets this ODD as the default to use.

The created ODD will be empty, but extends teipublisher.odd. If you would like to register an ODD you already have, use the file manager to copy it to resources/odd first. Afterwards follow the same steps as described here. Jinks will notice that the file already exists and will just register it.

What is important to know now is that adding an ODD to the configuration _after_ the app was initially generated _does not automatically use this ODD_. Very likely the text will still be rendered using the default teipublisher.odd, which is the fallback.

To fix this we need to run an action one time: actions are shown in the bottom toolbar of _Jinks_. Each profile may contribute its own actions, but there are four default actions always available. One of them is called Fix ODDs. Click on it to recompile all ODDs (which means to translate them into XQuery code) and wire them up correctly in the system. Once the process has completed, the new ODD will actually be used and you could start extending it.

![](jinks-action-toolbar.png) 

_Jinks action toolbar_

You only need the Fix ODDs action if you add or update an ODD in an already existing application, i.e. an application already installed into the database – or if there were _upstream updates_ to the profiles you use (see the section on applying updates below).

The same goes for the Reindex Data action: you only need to call it, if you changed the index configuration for an existing app.

## Downloading the application

_Jinks_ operates within the database, which means all files it generates and modifies exist inside the database only. To keep track of changes and to have a backup, you always want to download the generated files to the file system. There are two actions for this:

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 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 the development, to create snapshots to be committed to the source control repository, like Git.

![](jinks-sync.png) 

_Jinks Sync Action_

Both actions allow you to quickly retrieve a copy of your work. For more information regarding development workflows and later updates, please refer to the [reference guide](documentation.xml?id=development-workflow).

## Applying updates

There are two main scenarios in which you will update the application via Jinks (by pressing the Apply button):

1.  you modified the configuration: by changing settings, adding/removing profiles, uploading new files etc. This is what we've done above.

2.  a new version of TEI Publisher becomes available, which means you will update the version of Jinks installed, and – as a consequence – some of the profiles your app is using will have changed _upstream_.

_Jinks_ continuously tracks the files in your application to make sure updates will run smoothly. In particular, it needs to prevent that _upstream updates_, i.e. changes coming from a profile, will overwrite any change you have applied locally in your app.

Whenever you press Apply, the Command Output dialog will show you a list of files. To the left of each file you will see a label. In most cases this will just show _update_ with a green background. However, next to some files, brown _conflict_ label may appear.

![](jinks-conflict.png) 

_Command output dialog showing a conflict_

A _conflict_ means that _Jinks_ detected changes you made to this file since it was last updated, and it refused to overwrite this file with the original version coming from one of the profiles. For example, if I would change teipublisher.odd in my app (via the ODD editor), Jinks would detect this next time I press Apply and mark it as a conflict.

It is up to you to decide how to handle the conflict. You can tell _Jinks_  to ignore the conflict and overwrite the file with the _upstream_ version by clicking the Overwrite with next update button to the right of the entry.

Conflict over the teipublisher.odd would be an example of a change that likely should be reverted.  Custom ODD rules for your application should be given in your own ODD, which extends the teipublisher.odd,  instead of directly changing the base ODD.

You may also decide that the change is intentional, meaning that the conflict is expected and will stay. In this case, you may want to _whitelist_ the file.  Files referenced by the whitelist will not be touched by future updates. You can do so by adding it to the _skip_ property in config.json, which expects an array of paths relative to your application root:

```json
{ … "skip": [ "resources/odd/landing.odd", "resources/i18n/app/.+.json" ] … }
```

The paths are interpreted as regular expressions, so in the example above, we're skipping landing.odd as well as all i18n files ending with .json. 

With new _upstream_ versions of TEI Publisher or one of the profiles, you may need a hybrid approach,  namely add some of the _upstream_ changes, while retaining some of yours. In such case you need to manually edit the file in question.

To avoid unnecessary conflicts, it is important that customization changes go into files you have added yourself. It is easily possible, because TEI Publisher on many levels provides configuration options, which allow you to add custom CSS stylesheets, JavasSript, or API endpoints to your application without changing what is already there. Added, custom files will never trigger a conflict, because they only exist within your application.

## Operation modes

Tightly connected to updates and conflict detection are the three different operation modes _Jinks_ provides. You can switch between them through the select on the bottom of the Application Configuration tab: Quick update 
+  is the fastest mode and selected by default. It does not check every file for changes, but looks at the last modification date to see if there were changes to the _upstream version_ coming from the profile.

    Consequently it will not report conflicts if they can be safely ignored (because there are no upstream changes to overwrite them).

All 
+  checks the content of each file and compares it to the version last installed. This mode reliably detects and reports all potential conflicts.

Factory reset 
+  is the most drastic and dangerous of the modes: it completely deletes the installed application and recreates everything from the configuration. _Don't use it unless you have the current version safely backed up and really know what you are doing: you are certain you want to start from scratch, or you are a developer working on a profile for Jinks_!

# Changing the presentation via ODD

If you followed the steps so far and opened one of the sermons, you will notice that – while the default rendition of the text looks fine – some details are not quite right. For example, each sermon begins with the bible passage of the day and this should stand out a bit more.

We therefore need to change the ODD, barth.odd, which we created in the previous chapter. You have the choice between writing the ODD by hand (it is TEI after all) or using a form-based visual ODD editor. Both approaches can be combined and mixed. The visual editor saves the ODD in a non-destructive way, preserving any information not related to the processing models. It is therefore safe to switch between hand-editing the ODD and using the visual editor. Just make sure you reload the visual editor view after modifying the source XML and vice versa. That said, visual editor is specifically tailored to editing processing models so it will be likely the fastest and safest way to edit your ODD.

#### Important

If you edit the ODD XML by hand, there are some caveats you need to be aware of: the visual editor will automatically check if there are existing <elementSpec> s for a new element in any of the ODDs your ODD inherits from. When editing by hand, you need to do this yourself. It's best to always have the base [ teipublisher.odd ](odd/teipublisher.odd) open on the side. It is located in the same collection as your odd, i.e. /db/apps/tei-publisher/odd. 

For example, to modify the element spec for <dateline>, check  teipublisher.odd, where you will find a definition already. Copy it over to your ODD and start modifying it. 

Pay attention to the @mode attribute on <elementSpec>. You must set this to change if you are overwriting an <elementSpec> which already exists in the inherited ODDs. If not, set it to add. 

## First steps

To open the visual editor, go to the Admin menu (which is only visible if you are logged in), and select Edit ODD: barth.odd. A new tab opens, showing an action panel to the left, and the title of your ODD to the right. Initially your ODD will appear empty.

![](odd-empty-editor.png) 

_Empty ODD editor_

To be able to customize the display of your data it is crucial to understand its XML structure well. You can check the underlying XML using the corresponding links in the Download menu: you will see that the whole bible passage is marked up as an <epigraph> with a nested <cit>. The actual bible text is wrapped into a <quote> and the reference is encoded with a <ref> with `type="can"` and `subtype="bible"`:

```xml
<epigraph> <cit> <ref type="can" subtype="bible" target="Apk.1.8">Offenbarung 1,8</ref> <quote>Ich bin das A und das O, der Anfang und das Ende, spricht Gott der Herr, der da ist und der da war und der da kommt, der Allmächtige.</quote> </cit> </epigraph>
```

First, we may want to add some space before and after the epigraph, indent the bible text a little and render it in italics.

To create a processing model addressing this need we have to know three things: 

+  **when** should it be applied, 

+  **what** is supposed to happen 

+  and **how** should the text be formatted? 

Our first processing model should be applied to the <epigraph>, it should format it as a block-level element, and we would like to add margins before and after. In the Add Element input box to the left, enter `epigraph` and press on the + button.

A new tab will appear to the right, showing the existing definition for <epigraph>. Where does it come from? It is inherited from the base ODD, teipublisher.odd. It already contains generic rules for the most common TEI elements. All TEI-related ODDs in TEI Publisher extend this.

The existing model already treats <epigraph> as a `block` as can be seen in the behaviour setting. So all we need to do is to change the rendition to add margins.

Let's cover some key concepts of the TEI processing model first: <elementSpec> primarily documents the structure, content, and purpose of an element. It is a core element in any ODD but the schema-related functions are not relevant for the discussion here. What is important for us is this is where processing models are defined. The @ident attribute of the <elementSpec> identifies the name of the element to which the spec (and therefore processing model) applies. 

An <elementSpec> may contain one or more <model> elements to specify the intended processing of this element. Every model maps the element to a behaviour. A behaviour denotes an abstract transformation function to be applied. The TEI guidelines currently list two dozen behaviours, e.g. paragraph, heading, note, inline, block. The last two are the most frequently used. How exactly a behaviour translates into the target output media may differ depending on media features and design decisions. TEI Publisher tries to implement them as generically as possible.

## Using output renditions

The processing model uses <outputRendition> and CSS to define visual aspects. For output formats other than XML, the CSS is translated into the corresponding target language. It is thus best to limit the CSS to the most common typographical features, like bold, italic, color, underline etc. The general styling of the text should be done outside the ODD to maintain a clear separation of concerns.

To add some top and bottom margin to the <epigraph>, click on the + next to Renditions. This opens a new input into which we can enter CSS. For the margins and padding, we can simply add:

```css
margin: 1rem 0; padding: 0 2rem;
```

![](odd-epigraph.png) 

_elementSpec for epigraph with renditions_

Once you're done with the change, click on the button with the disk symbol in the toolbar to the left to save and compile the ODD. A pop-up will appear, reporting the result of the compilation process:

![](odd-popup.png) 

_Pop-up displayed after saving ODD_

TEI Publisher compiles the ODD into executable XQuery code. For each output media format supported, one XQuery module is created as reported in the screenshot.

Eventually this process may fail, e.g. if you entered incorrect XPath expressions somewhere. In this case the pop-up will report the failure for each output format. It still saves the resulting XQuery code into a file with the marker `.invalid` in its name, e.g. barth-web.invalid.xql. If you cannot figure out your mistake otherwise, it sometimes helps to open the invalid XQuery in eXide, enter a space somewhere to trigger validation and look at the error message eXide gives you, which is often quite helpful. Don't be afraid of the XQuery code: the mapping between the ODD and the generated XQuery is actually quite straightforward.

This said, the visual ODD editor does also run syntax checks on all XPath statements and you should pay attention to any red markers to avoid running into issues.

Switch back to the tab with the sermon text from which you opened the editor and refresh the browser window to see your changes applied. In case you do not see any change, make sure 

1.  you are using the correct ODD: the URL should contain a query parameter odd pointing to the name of your ODD. If not, go back to the Jinks section and check if the `defaults.odd` configuration property is correctly set to your ODD.

2.  if you made changes to <outputRendition>s only, you may need to clear your browser's cached version. For most browsers, holding the _Shift_ key while clicking on the _Reload_ button does the job.

Instead of using the visual ODD editor, we could also work directly on the XML of the ODD. You can see the XML by clicking on the <> toolbar button to the left. For reference, our <elementSpec> for <epigraph> should currently look as follows:

```xml
<elementSpec ident="epigraph" mode="change"> <model behaviour="block"> <outputRendition xml:space="preserve"> margin: 1rem 0; padding: 0 2rem; </outputRendition> </model> </elementSpec>
```

## Conditions and multiple models

Next, we'd like to format the bible quote and make the text italic. If you add an <elementSpec> for quote, you will see that it has two models by default. The first one has a condition, which is reflected in the description and the corresponding XPath printed in red below. Conditions allow you to distinguish uses of the same element in different contexts. In the given scenario, <quote> will be rendered inline if it has a <p>, <cell> or <cit> ancestor. Otherwise the second model outputs it as a block.

The processing model uses a predicate to make such distinctions: a model rule will only be used if the XPath expression in its predicate matches the current node being processed. And if there's more than one <model> within an <elementSpec>, only the first model matching all conditions will be used. Any model after the matching one will be ignored.

Since our <quote> is indeed located within a <cit> element, we have to modify the first model:

![](odd-quote.png) 

_elementSpec for <quote>_

The sermons look better now, but we still have the bible reference inlined before the bible quote. We want to make this a block and center it:

1.  add an <elementSpec> for ref with behaviour `block`

2.  it should be limited to canonical references, which we could express by adding a predicate `@type="can"`. However, this would apply to all bible references in the text. Therefore the predicate needs to be further limited to canonical references within the epigraph:

```xquery
@type="can" and ancestor::epigraph
```

3.  add an <outputRendition> to center the text:

```css
text-align: center;
```

Applying this change, the bible reference becomes centered above the bible passage. So far so good. Unfortunately it is no longer a link because we turned it into a block. To again make it a link, we need to introduce another key concept: _parameters_.

## Using parameters

All behaviours accept one or more parameters which are defined in the TEI guidelines. Every behaviour has an implicit parameter called content, and, as the name suggests, it specifies which part of the source document should be processed: by default it uses the nested content of the node. You may overwrite this default and assign it another value. Some behaviours take other specialized parameters. For example, the  alternate behaviour accepts two parameters: default and alternate. An alternate switches between two alternative states. On the web this could take the form of a pop-up, in print it is usually implemented as a footnote.

The link behaviour accepts two extra parameters:

uri 
+  the URI to link to

target 
+  corresponds to the [HTML attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a#target) of the same name and determines how the link would be opened in a web browser

We'll switch our model for <ref> to use link and set both parameters:

1.  change the behaviour of our model to link

2.  in the Parameters section, add a parameter and set its name to `uri`

3.  for the parameter value, let's create a proper URL pointing to an external service to give readers the possibility to read the bible passage in context:

```xquery
'https://www.bibleserver.com/LUT/' || @target
```

    The `||` expression is a string concatenation operator in XPath/XQuery: we append the content of the @target attribute to the base URI pointing to the online Luther Bible.

4.  add another parameter named target with value `'_blank'`. This will result in the link being opened in a new browser tab (unless the user configured the browser to behave differently).

5.  a link is an inline element. To still render it as a block and center it, we can change the CSS in the <outputRendition>:

```css
display: block; text-align: center;
```

![](odd-bible-ref.png) 

_Add a model for ref_

Clicking on the bible reference will now open a new tab and load the external _bibleserver_ service, which nicely displays the bible passage in context.

Obviously the _bibleserver_ provides a much more modern version of Luther's bible than the one Karl Barth used back in 1915. The proper [Karl Barth Gesamtausgabe](https://kbga.karl-barth.ch/texts/27003) integrates the correct version (published 1912) as XML, but that version unfortunately is not freely available.

However, you may note that bible references elsewhere in the text are still wrong, i.e. leading nowhere. Fixing this should be easy, but we'll leave this as an exercise.

# Further steps

This brief introduction aims to give a very basic orientation in using Jinks and TEI Publisher. For more in depth discussion of various subjects you may want to check the [Reference Manual](documentation.xml) and [Web Components](webcomponents.xml).

e-editiones runs a series of monthly community meet-ups and also maintains a Slack community, which provide a space for discussion, coordination of efforts and community support. Check the [website](https://www.e-editiones.org) to find meeting announcements and recordings of past presentations and workshops.