EVT 2.0 (evt-viewer)

1 - Introduction

1.1 - About EVT

EVT (Edition Visualization Technology) is a light-weight, open source tool specifically designed to create digital editions from texts encoded according to the TEI XML schemas and Guidelines, freeing the scholars from the burden of web programming and enabling the final users to browse, explore and study digital editions by means of a user-friendly interface.

This tool was born in the context of the Digital Vercelli Book project, in order to allow the creation of a digital edition (which has been available in beta form for more than two years) of the Vercelli Book, a parchment codex of the late tenth century, now preserved in the Archivio e Biblioteca Capitolare of Vercelli and regarded as one of the four most important manuscripts of the Anglo-Saxon period as it regards the transmission of poetic texts in the Old English language. However it has evolved into a tool suitable to fit different texts and needs. For example, it is now being used to publish the digital edition of the Codice Pelavicino manuscript, a medieval codex preserving charters dating back to the XIII century. The continuous development and need to adapt it to different types of documents and TEI-encoded texts has shifted the development focus towards the creation of a more general tool for the web publication of TEI-based digital editions, able to cater for multiple use cases.

The entire structure of the software has been remodeled, in order to make it lighter, more usable and more adaptable; we decided to use the Model View Controller (MVC) approach, that is a very common architectural pattern in object-oriented programming, that allows to separate the logical presentation of the data, from the application logic and the processing core. Wanting to maintain the original feature of EVT, and therefore do not give up the client only approach, we decided to use AngularJS, a JavaScript framework inspired by the MVC programming logic, especially suitable for the development of client-side Web applications; among other things, this framework allows to define custom HTML components and use the data-binding mechanism to associate the model of the data to the UI elements, and manage the updates of the latter avoiding the direct DOM manipulation.

1.2 - How it works

Before the refactoring, EVT was composed of two main units: EVT Builder, for the transformation of the encoded text using special XSLT 2.0 templates, and EVT Viewer, for the visualization into a browser of the results of the transformations and the interaction with them. The idea under the new version of EVT is instead to leave to EVT Viewer the task of reading and parsing with JavaScript functions the encoded text, and “save” as much as possible within a data model, that persists in the client main memory, and is organized in a way that allows a very quick access to the data in case of need. This has obviously led to the elimination of the EVT Builder level, and therefore it allows to open a digital edition directly in the browser without any previous XSLT transformation.

Please note that starting from version 67 Firefox developers adopted the same security-conscious policy chosen by developers of Chrome and other Web browsers, that is forbidding loading local files (= documents available on the user’s computer drive) in the browser as a result of the execution of Javascript programs. The goal is to improve global security when browsing the Web, but the unpleasant collateral effect is that of preventing the loading of digital editions based on EVT, or similar software, from local folders. Fortunately there are several workarounds that can be used to test EVT editions that are located on your hard drive:

This problem, however, only affects local testing, after the edition has been uploaded on a server there are no problems in accessing it with any of the major browsers.

1.3 - Main features

At the present moment EVT can be used to create critical editions with multiple levels of apparatuses, encoded using [the TEI Parallel Segmentation Method] (http://www.tei-c.org/release/doc/tei-p5-doc/en/html/TC.html#TCAPPS). This means that a transcription encoded according to the Guidelines should already be compatible with EVT 2, or require only minor changes to be made compatible.

Among the main features you will find: Critical edition support. Enlarged critical apparatus, sources apparatus and analogues apparatus, variant heat map, witnesses collation and variant filtering are some of the main features developed for the critical edition support. Bookmark. Direct reference to the current view of the web application, considering view mode, current document, page and edition level, eventual collated witnesses and selected apparatus entry. Named entities and lists of entities. Interactive bibliography. User can visualize the bibliography of the edition and reorder the entries by author, publisher or publishing date. * High level of customization. The editor can customize both the user interface layout and the appearance of the graphical components.

2 - A short guide to EVT

EVT 2 can be used to prepare an edition right away, immediately after installing it on your hard drive: see the Installation and use section first, then Configuration, to understand how EVT works and how you can use it to publish your editions. A more detailed guide will be published separately, as a reference manual, and will also include instructions about customization.

If, on the other hand, you are interested in developing a specific functionality in EVT 2, or in modifying an existing one, we suggest that you download and install the Development framework. The README.md contained in it explains how to install and configure the development framework needed for this purpose. This step is only needed if you want to start working with EVT’s source code, so it is in no way necessary for basic users.

2.1 - Installation and use

Installation is quite simple, download the compressed archive from EVT’s home page, unzip it in a suitable location on your hard drive, and you are ready to use it:

2.2 - Configuration

There are several configuration options, ranging from the folders where edition data is stored to User Interface layout and available tools, that can be set by editing the config.json file in the config directory. Below you will find a detailed list of the available options: in the file you will see a list of options on the left, to configure EVT you will have to insert the appropriate values in the textual fields on the right. Sometimes those values will consist of boolean strings (“true” or “false”), sometimes they will be simple character strings (e.g. "Interpretative edition"), in other cases you will have to enter TEI XML elements (e.g. ", "); for colors it will be necessary to specify the correct RGB values (e.g. "rgb(108, 145, 207)").

If you find this file difficult to read and/or change you can try out the beta EVT2-Config-Generator: upload the current config.json, change the parameters you need to change and download the new config.json. Note that this is the first version of the EVT2 Config tool, so there may be glitches and/or problems, please report them to us.

Main edition data

Edition main information
Source files
VisColl files
View modes
Edition levels
Edition navigation

Generic tools

Named entities

Critical edition

Witnesses
Witnesses Group(s)
Apparatuses

EVT 2 is able to handle multiple levels of apparatuses: critical entries apparatus, sources apparatus and analogues apparatus. In "Reading view", all of them can be available both in inline mode (the apparatus will appear within the text, right after the portion of text to which it is connected) or in a separate box (there will be a container next to the main text where all the entries will be shown and aligned to the text, whenever the user clicks on an entry). By default, all the apparatuses will appear separately from the main text, but you can choose which mode you prefer by setting to true (inline) or false (separate box) the following parameters: showInlineCriticalApparatus, for critical apparatus entries; showInlineSources, for apparatus of sources; showInlineAnalogues, for apparatus of analogues. showReadingExponent. Indicate if you want to use alphabetic exponent for critical entries (true) or not (false).

Tools
Multiple recensions
Advanced Settings

Tell the system how to recognize the data: indicate which XML tag you used for the encoding of the different objects.

XML Tag usage configuration listDef. List of Witnesses: element(s) you used to encode the lists of all the witnesses or changes referred to by the critical apparatus (f.i. <listWit> or <listChange>). Please divide values using commas. versionDef. Single witness: element(s) you used to encode a single witness or change referred to within the critical apparatus (f.i. <witness> or <change>). Please divide values using commas. fragmentMilestone. Fragment milestones: element(s) you used to indicate the beginning (or resumption) and the end (or suspension) of the text of a fragmentary witness (f.i. <witStart> or <witEnd>). Please divide values using commas. lacunaMilestone. Lacuna milestones: element(s) you used to indicate the beginning and the end of a lacuna in the text of a mostly complete textual witness (f.i. <lacunaStart> or <lacunaEnd>). Please divide values using commas. notSignificantVariant. Not significant variants: element(s) of attribute(s) you used to encode variants that are not significant and you do not want to appear in the main critical apparatus (f.i. <orig>, <sic> or @type=orthographic). Please divide values using commas. quoteDef. Quotes: element(s) used within the XML file to encode quotes for the sources apparatus (f.i. <quote>). Please divide values using commas. * analogueDef. Analogues: element(s) used within the XML file to encode passages for the analogues apparatus. (f.i. <seg> or <ref[type=parallelPassage]>). Please divide values using commas.

Filters possibleLemmaFilters. Possible lemma filters: attribute(s), divided by commas, you want to consider as possible filters for lemmas (f.i. resp or cert). If you want, you can customize the color of each filter value in the tab "Colors" (otherwise random colors will be used). possibleVariantFilters. Possible variant filters: attribute(s), divided by commas, you want to consider as possible filters for variants (f.i. type, cause or hand). If you want, you can customize the color of each filter value in the tab "Colors" (otherwise random colors will be used).

Colors variantColorLight and variantColorDark. Generic variant Colors: customize the highlight colors (both dark and light for selected and unselected entries) for generic variants that do not have any specific metadata (or have metadata that are not considered as filters). Default colors are rgb(208, 220, 255) (light) and rgb(101, 138, 255) (dark). heatmapColor. Heat Map Color: customize the highlight color for variants when the heat map tool is activated (this will be the darkest color possible, that means the color of entries with the highest variance level). Default color is rgb(255, 108, 63). * variantColors. Specific Variant Colors: customize the highlight color for each value of each lemma filter you defined in possibleLemmaFilters and each reading filter you defined in possibleVariantFilters. If you do not define a specific color, the system will use a random one.

Miscellaneous settings

Bibliography
Search engine
Image viewer options
3D viewer options
Languages

3 - Examples

There are several ready-to-use examples. The one used by default is n. 1.

If you want to explore the other two you will just have to open the corresponding settings file (f.i. config_marlowe.json) and save it as the main config.json file, overwriting the existing configuration. Then go to the index.html opened in your browser and reload the page!

4 - EVT Manual

Work in progress, a preliminary version is available in the doc folder.

5 - Feedback

User feedback is very much appreciated: please send all comments, suggestions, bug reports, etc. to evt.developers@gmail.com.