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.
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:
-
your encoded edition document must be copied in the
data/text
directory: EVT comes with a default directory structure, distinguishing between images, text and other types of data, but you can modify it as desired, provided that the appropriate paths are specified in the configuration file (config.json
, see below); -
to have it parsed and loaded by EVT you have to point to it explicitly modifying the
config.json
file in theconfig
directory:"dataUrl": "data/My edition.xml",
; note that there are several other configuration options available in that file, so that you can customize the layout and appearance of your edition; also note that some configuration options may be necessary to make desired features available, for instance to add the required edition level, so make sure you read the following section and check the default configuration file. -
optionally, you can add your own CSS instructions to modify the appearance of specific TEI elements by editing the
config-style.css
file in theconfig
directory. The customization of generic and linear TEI element is very simple, even if EVT does not yet consider them in the default visualization: in fact, the TEI elements which are not handled in any particular way by EVT are always transformed in HTML elements with the TEI tag name as class name. In this way, the customization is very easy: just add a rule that match the tag name of the TEI element to style. F.i., a deletion encoded withdel
element, can be displayed with a line through the text just by adding the rule.del { text-decoration: line-through; }
.
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](http://evt.labcd.unipi.it/evt2-config/): 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 Data
Edition Main information
indexTitle
. Choose a title for your edition. If you leave it blank the default 'EVT Viewer' title will be shown.webSite
. If you specify an external web site there will be a link pointing to it.logoUrl
. You can also add a custom logo that will appear before the edition title: just indicate the path to it; it can be a URL or a relative path: we suggest that you put it intodata
and point to it (f.i.data/icons/myLogo.jpg
).
Source file(s)
dataUrl
. Indicate the file name of the XML file of your encoded edition. It can point either to an internal folder or to an external online resource.sourcesUrl
. Indicate the file name of the XML file encoding the list of all the bibliographic references for the sources apparatus. It can point either to an internal folder or to an external online resource.analoguesUrl
. Indicate the file name of the XML file encoding the list of all the bibliographic references for the analogues apparatus. It can point either to an internal folder or to an external online resource.sourcesTextsUrl
. Indicate the folder where you intend to put the XML containing the texts of external sources (if you have any).enableXMLdownload
. Decide if you want to enable the XML download (true
) or not (false
).
Edition levels
availableEditionLevel
. Select which edition levels you want to be available in your edition. You can deactivate a view mode both by deleting it and by setting tofalse
the propertyvisible
(the latter being the suggested method). If you select just one edition level you can choose either to display the selector (with just one item) or not by settingshowEditionLevelSelector
respectively totrue
orfalse
.defaultEdition
. Select which edition level you want to your edition to open on. Note that it must be an active edition level!showEditionLevelSelector
. Decide if you want to display the edition level selector (true
) or notfalse
. This parameter is considered only if you select just one edition level: if there are two or more edition levels available, the edition selector will be always visible.
Generic Tools
View Modes
availableViewModes
. Select which view modes you want to be available in your edition. You can deactivate a view mode either by deleting it or by setting the propertyvisible
tofalse
(suggested method).defaultViewMode
. Select which view mode you want to your edition to open on. Note that it must be an active mode!
Bibliography
allowedBibliographicStyles
. Select which bibliographic style you want to enable. Bibliographic styles will work properly if the system will find all needed information encoded in you XML file. You can deactivate a bibliographic style either by deleting it or by setting the propertyenabled
tofalse
(suggested method).defaultBibliographicStyle
. Select which bibliographic style you want to your edition to open on. Note that it must be an active bibliographic style!
Tools
toolPinAppEntries
. Select if you want to activate (true
) or not (false
) the PIN tool, which allows the user to “save” apparatus entries or (named) entities in order to reach them more quickly when you need them.toolImageTextLinking
. Select if you want to activate (true
) or not (false
) the Image-Text Linking tool, which allow the user to connect line by line the facsimile to the transcription. You will need to properly encode thezone
and their coordinates and have Image-Text among the available view modes. Note that this is still a work-in-progress feature since we are still implementing the EVT 2 image viewer.namedEntitiesSelector
. Select if you want to activate (true
) or not (false
) the (named) entities selector, which allow the user to highlight on the text one or more specific (named) entitie(s).namedEntitiesToHandle
. Customize the list of available named entities to be highlighted and to be shown among entities lists, by adding a new element in this list: for each element you should define atagName
, which is the XML tag that identify the entity and alabel
that will be shown in the selector. If you don’t need an entity that is already inserted in this list you can delete it or just use the propertyavailable
set tofalse
(suggested choice). Note that EVT can work properly only withpersName
,placeName
andorgName
; any other type of entity might cause problems (hopefully not!). If you need a new kind of named entity to be handled just notify the EVT Development Team.otherEntitiesToHandle
. Customize the list of available entities to be highlighted by adding a new element in this list: for each element you should define atagName
, which is the XML tag that identify the entity, alabel
that will be shown in the selector and acolor
that will be used to highlight the entity within the text. If you don’t need an entity that is already inserted in this list you can delete it or just use the propertyavailable
set tofalse
(suggested choice).
Languages
languages
. Customize the languages you want to set as available for the translation of the User Interface (just the UI!) by adding their codes in this list. At the moment we support just english ('en'
) and italian ('it'
). If you want to add the support for a new language, just add a new*new_language_code*.json
inside thei18n
directory and a*new_language_code*.png
image inside theimages
folder.
Critical Edition
Witnesses
preferredWitness
. Indicate the sigla of your preferred witness; this will be used everywhere if you forgot to encode the lemma for a particular variation of the text.skipWitnesses
. Indicate the siglas (divided by commas) of witnesses you want to exclude from visualization.
Witnesses Group(s)
witnessesGroups
. If you want, you can divide the readings of all critical apparatus entries into groups. Each group should have awitnesses
property (mandatory) that indicates the siglas of witnesses within the group and agroupName
(optional) that indicates the name of group to be displayed (f.i.{ “groupName”: “Group 1”, “witnesses”: “A, B, B1” }
).
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.
Tools
showReadingExponent
. Indicate if you want to use alphabetic exponent for critical entries (true
) or not (false
).toolHeatMap
. Indicate if you want to include the Heat Map tool within the Critical Edition box (true
) or not (false
). This tool gives the user an overview about text variance.
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
orcert
). 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
orhand
). If you want, you can customize the color of each filter value in the tab "Colors" (otherwise random colors will be used).
Colors
variantColorLight
andvariantColorDark
. 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 arergb(208, 220, 255)
(light) andrgb(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 isrgb(255, 108, 63)
.variantColors
. Specific Variant Colors: customize the highlight color for each value of each lemma filter you defined inpossibleLemmaFilters
and each reading filter you defined inpossibleVariantFilters
. If you do not define a specific color, the system will use a random one.
3 - Examples
There are 3 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 config.json file (f.i. config_ex2.json), copy its content and paste it into the main config.json file overwriting the existing configuration. Then go to the index.html opened in your browser and reload the page!
-
EXAMPLE 1: avicenna.xml - Short extract of Edizione Logica Avicennae, changed by CM for EVT testing purposes. It presents multiple levels of apparatuses (critical entries, sources and analogues), displayed in a separate dedicated frame. Configurations for this edition: config_avicenna.json
-
EXAMPLE 2: pseudoEdition.xml - Pseudo edition for demonstration and testing purposes only, originally encoded by Marjorie Burghart for her TEI Critical Toolbox software, and modified in order to cover the highest number of possible use cases. It presents just the critical apparatus entry, displayed inline, within the main text. Configurations for this edition: config_pseudoEdition.json
-
EXAMPLE 3: pelavicino.xml - Short extract of the Codice Pelavicino edition, which presents the encoding of named entities, in particular person, place and organization names. Configurations for this edition: config_pelavicino.json NB: Note that at this time EVT 2 can support diplomatic editions only in a limited way, feature parity with the previous version will come next year.
-
EXAMPLE 4 : marlowe.xml - Short extract of The Tragedie of Doctor Faustus (B text) by Christopher Marlowe. Text provided by Perseus Digital Library, with funding from Tufts University. Original version available for viewing and download at http://www.perseus.tufts.edu/hopper/. Configurations for this edition: config_marlowe.json
4 - EVT Manual
Work in progress... stay in touch!
5 - Feedback
User feedback is very much appreciated: please send all comments, suggestions, bug reports, etc. to evt.developers@gmail.com.