1. Introduction

	TEICHI 0.6	VM 4.0	SADE
Target projects	Digital editions of printed material with a simple editorial situation	Digital editions of shorter material, such as poetry, with many textual witnesses	Flexible, depending on setup; also for bilingual editions
Basic layout	One text column, tools and notes in the margins, toolbar at the bottom	Any number of columns displaying textual witnesses or bibliographic metadata	Flexible: one or two text columns plus navigation and index/search sidebars
Relation to website infrastructure	Modules integrated into Drupal 7	Can be integrated into any website or used offline	Provides full website infrastructure
Transformation	Takes place on the server	Takes place in the browser or is done prior to publication	Takes place on the server
Support for TEI elements	Majority of TEI Lite, plus specific support for the ‘choice’ element	Parallel segmentation and location-referenced encoding, most editorial interventions, and various types of notes	Flexible, depending on custom XSLT and CSS files

Table 1: Comparison of TEICHI, the VM, and SADE

2. Reading and Viewing: The User’s Perspective

7We would like to start with the user perspective, in which several elements come into play: the overall look and feel of the site, the navigational aids, the display features of the text, the interaction that is possible, and the information retrieval tools provided.

8Because TEICHI is fully integrated into Drupal, the overall layout depends on the theme chosen and the block regions used. TEICHI has proven to be compatible with the Garland and Bartik themes, each offering fully customizable color schemes and providing numerous block regions. Apart from the header and footer blocks, TEICHI uses a one-column layout for the main text with a large margin to the right where the notes are displayed. Additional tools for download and search may be placed in any of the block regions. There is a fixed bottom toolbar providing some of the navigational aids and interactive features. This basic layout is shown here on the basis of an implementation of TEICHI we undertook (see fig. 1 and Bérardier de Bataut 2010).

9Text in TEICHI is structured not into individual pages, but into chapters or sections ordered hierarchically as in the TEI text division structure. Navigation inside these books can be from one chapter or section to the next or previous, as well as one level up. The TEICHI toolbar provides additional navigational aids: a page index of the current chapter or section and a “go to” feature allowing users to go to any page of the current book. Page numbers can be displayed (inline), but there is no option for line numbering. Digital facsimiles of individual pages can be viewed by clicking on the page numbers, but this feature is very basic; there is no two-column layout or pop-up image viewer that conveniently permits comparison of the facsimile and transcription. Text display is focused on one main column with author and/or editor notes placed in the right margin and collapsed by default to avoid an overly cluttered page. The user can toggle between two views of the text: one linear transcription of the text and one modernized, corrected, or otherwise regularized reading text. All words affected by variation between these two transcriptions are highlighted by colored backgrounds. Apart from the opening or closing of notes and the navigational aids, interaction with the edition in TEICHI primarily concerns this view toggle option.

10Users can retrieve the texts from the online edition via a download block that provides various download options: an EPUB version for offline reading with an e-book reader or smartphone, a plain text version for use with basic text analysis tools, and the TEI source for further use with advanced XML-aware text analysis tools. For all of these file formats, the user can also choose between various renderings of the text: either the linear transcription or the reading text, with or without editorial notes, or a single chapter or several chapters, placed either in separate files or in one single file.

11When comparing TEICHI to the VM, the first thing any user will probably notice is that the VM allows any number of columns of text next to each other, while TEICHI provides only one. Second, interaction with the edition is much greater in the VM, since the user can choose what to display in any of the columns, be it metadata, critical notes, or any of available versions of a text. Also, the user of the VM can decide whether to display line numbers and whether to display notes inline or as mouse-over popup notes. Individual lines can also be highlighted in all of the currently displayed versions of a text, helping to compare them. There is an image viewer and files can be downloaded directly from the browser. The VM does not offer any support for building a website around the edited texts; instead, it must be integrated into an external website. All of the existing implementations of the VM are quite similar in layout and with regard to the features offered (see, for instance, Freytag-Loringhoven [2009] in fig. 2, or the Digital Ælfric Project [2011], the latter providing no less than 17 witnesses of some of Æelfric’s Catholic Homilies).

13It appears from this comparison that SADE is highly customizable and hence suitable for a variety of use cases, while TEICHI and the VM are each best suited to the display of specific types of documents. TEICHI is designed for editions dealing with multiple relatively long non-manuscript texts, each with a straightforward editorial situation, where the editor chooses to present only one print edition. The VM favors shorter print or manuscript texts, especially poems of which many differing versions exist and which can be displayed and compared with great convenience. From a user perspective SADE’s ability to accommodate a wide range of editions does not overwhelm the user for any particular document or intended use, while an advantage of the VM and, arguably, of TEICHI is that they provide particularly neat solutions for specific use cases.

3. Encoding: The Editor’s Perspective

15TEICHI’s support of TEI encoding schemes is currently limited to a subset of TEI Lite, although this situation is expected to change in the near future. The principal aim of TEICHI is to provide the editor with a means of encoding and displaying a linear transcription of the source text. Typically this type of edition retains many particularities of the source while also documenting and/or displaying a certain degree of correction, regularization, and modernization. This is primarily achieved through the use of the well-known and simple <choice> mechanism of TEI. This means that although only one edition of a given text can be represented, two alternative readings of it can be displayed. Also, TEICHI allows the editor to add authorial and editorial annotations in an unobtrusive way by means of the <note> tag. Moreover, TEICHI extracts information on page numbering from the TEI documents and uses this automatically to provide help navigating longer texts.

17In contrast to the rather basic support for editorial interventions and textual variants of TEICHI (which does not go beyond the possibilities offered by TEI Lite), the VM supports TEI’s very powerful Text Criticism module, which is essentially based either on the parallel segmentation or the internal location-referenced method of encoding described in the TEI Guidelines (Burnard and Bauman 2007, sec. 19.2.3). This is an efficient and precise, but relatively complex, way of encoding multiple versions of a text. From an editorial point of view, it has the benefit of not requiring the encoder to declare a base text (Schreibman et al. 2007). While the VM does not make the locus and extent of variation between versions explicit, the tool’s advanced display options easily make up for this. The VM provides quite extensive documentation, especially on encoding documents but also concerning internal file and folder structure and customization options of the tool. In addition, there is a form for bug reports on the project website.

18Compared to TEICHI and the VM, SADE again offers a much more open feature set. Basically, any TEI-compliant XML document can be used because SADE comes with support for the TEI’s own stylesheet library, thus accommodating a much more diverse scope of encoding needs and possible use cases. However, this comes at the expense of lacking the “out-of-the-box support” that TEICHI and the VM provide for those features and TEI modules that fall into their specific application domains.

19Thus, from the editor’s perspective, TEICHI and the VM cater directly to their specific needs and have a clear scope in terms of tag coverage. While SADE does not have any built-in limitations, it requires customization for any given project and comes with a steeper learning curve. Before we move on to the administrator’s perspective, we summarize our comparison in table 2.

	TEICHI 0.6	VM 4.0	SADE
Page layout	1 text column, plus 1–2 sidebars, depending on setup	Any number of columns, adjustable by user	Flexible: 1–2 text columns, 0–2 sidebars, depending on setup
Text structure	One page per chapter or section; page numbers	One page per document; line numbers	Flexible: page-by-page or one page per section or text
Multiple text versions	Toggle mechanism via <choice>	Any number of transcriptions via parallel segmentation or internal location-referencing	One or two transcriptions side-by-side
Annotation	Author’s and editor’s notes, collapsible, in sidebar	Four types of notes, as tooltip or in separate column	In right sidebar by default; depends on setup
Digital facsimiles	Very basic	Popup image viewer	Inline image viewer, depending on setup
Search	TEI-aware	No	TEI-aware
Download formats	EPUB, TXT, XML/TEI via download block	XML, HTML via browser	HTML, PDF, EPUB, DOC via icons

Table 2

4. Installation: The Administrator’s Perspective

20From the administrator’s perspective, the most important aspects are the hardware and software requirements, the ease of setting up the server, installing the tools, customizing them, and having support for all these tasks including some type of documentation.

22The VM has even lower system requirements than TEICHI since it does not require a webserver and thus can be used offline. Installing the VM is straightforward since there is basically no installation procedure other than unzipping the files and copying the XML/TEI or HTML documents into the right folder. Following that, the files can be opened in a browser. On the other hand, making the documents publicly available requires a webserver. Besides the webserver itself, setting up the VM for online use should not pose any major challenges. The drawback is that the organization and structure of the website are left to the administrator. Another downside is that either the TEI files must be transformed in advance to HTML, or the user’s browser must perform the XSLT conversion. No help can be expected from the VM running on a webserver for this transformation.

23SADE requires one of the latest versions of the Java SE Development Kit for the application server Jetty, which it includes. SADE is distributed as a ZIP archive containing ready-to-use install files, including the Jetty server and eXist-db components. This means that SADE can easily be used on a dedicated server but is not as easily deployed in shared hosting environments. Also, setting up SADE is somewhat challenging and the average humanities scholar will probably not be able to do this without support, since several fairly complex technologies must be made to work together. Another difficulty arises from the fact that documentation concerning SADE is very limited. Like TEICHI (through Drupal) and unlike the VM, SADE offers many options to build comprehensive websites.

24From the administrator’s perspective, then, it appears that the VM is the tool with the lowest demands, followed closely by TEICHI. SADE is clearly the most complex and challenging publishing framework. Note also that despite the divergent server-side requirements, all projects require JavaScript-capable browsers on the client side.

5. Tool Building: The Programmer’s Perspective

25From the programmer’s perspective, it is important to look at the tool’s architecture. Each tool has a particular way of implementing its features, and its architecture determines how easy it is to integrate digital editions into a broader website environment. The first part of this section gives a rough overview of how TEICHI works and is mainly meant for readers not familiar with Drupal. Due to the specifications of the Drupal framework and the use of the standard method of transforming TEI to HTML by employing an XSLT processor, this part of the section will hardly contain any surprises for advanced readers. The second part of the section then shortly compares the differences in the tools’ chosen implementations.

27Drupal stores input in a raw format in its database. Then, prior to displaying any output in a browser, it processes the content by applying rules defined for each input format. Input formats themselves are represented by an ordered collection of filters where each filter feeds its output to the next filter. Filters are simply sets of rules which are applied to transform their input in some way. If used wisely, this concept allows great flexibility by defining simple filters and making them work together. Within this paradigm, TEICHI is such a filter implementing the transformation from TEI/XML to XHTML by an XSLT processor. By assigning CSS classes to certain HTML elements corresponding to their original XML elements, it is then possible to determine the desired layout. Further functionality, like switching between variant readings and navigating to original page numbers, is implemented by adding JavaScript. The largest advantage of this approach is that all information within the original data is kept. This is especially useful for TEI documents since different transformations to various output formats are thus possible.

28Besides scripts run for installing and uninstalling, the TEICHI main module contains JavaScript files, the XSL stylesheet for rendering, and some files needed for Drupal. The main file with the Drupal-compliant name teichi.module contains PHP functions. Many of those functions use the previously described hooks. The most important of them is teichi_filter_info (see fig. 5), which determines which function is called when a node with content type teichi is shown.

function teichi_filter_info() {
 $filters[‘teichi’] = array(
   ‘title’ => t(‘XSL filter for TEIChi module’),
   ‘process callback’ => ‘_teichi_transform’,
   ‘tips callback’ => ‘_teichi_filter_tips’,
   ‘cache’ => FALSE,
 );
 return $filters;
}

Figure 5

function _teichi_transform($xml, ...){ 
  // some error checks
  ...
  // set TEI XSL file,
  $path_to_xslt = drupal_get_path(‘module’,’teichi’).’/xsl/drp_style.xsl’;
  // add Javascript files
  ...
  drupal_add_js(drupal_get_path(‘module’,’teichi’).’/js/drp_main.js’);
  // add CSS file
  ...
  drupal_add_css($cssPath, $options);
  // Transformation
  // Load the documents
  $dom = new DomDocument(‘1.0’, ‘UTF-8’);
  $dom->loadXML($xml); ... 
  $xsl = new DomDocument(‘1.0’, ‘UTF-8’);
  $xsl->load($path_to_xslt); 
  // Create the XSLT processor and transform
  $proc = new XsltProcessor();
  $xsl = $proc->importStylesheet($xsl); 
  $newdom = $proc->transformToDoc($dom);
  $out = $newdom->saveXML();
  return $out;
}

Figure 6

30There are also numerous functions providing uploads for TEI/XML files or fonts and for making adjustments to TEICHI’s configuration. It is worthwhile mentioning that the TEI Search module adds a second filter which gets the output of the main module’s filter and changes it, e.g. to highlight searched words.

31Besides the main content handled via filters, modules may also provide additional content or features. These are made available as blocks which can be positioned inside the theme(s) used. The TEI Download module provides a block with a configurable set of items. These let the user download the node content in various formats: EPUB, plain text, or TEI.

32To implement the block, two functions are needed which make use of Drupal’s hooks: teichidownload_block_info(), with the block’s basic definition, and teichidownload_block_view(), which defines the block’s content. The latter first tests whether the actual node type is a teichi node and whether the user has sufficient rights to view the block. If this requirement is fulfilled, a generic Drupal function is called which creates the block’s content by invoking the module’s form constructor function. If the user picks one of the download icons and submits the form, the form’s values are validated and then passed to the teichidownload_form_submit() function (see fig. 7). Depending on the value submitted, the appropriate function is called to generate the document to download.

function teidownload_form_submit($form, &$form_state) {  
 $nid = arg(1); 
 $button = $form_state[‘clicked_button’][‘#name’]; 
 switch ($button) { 
  case ‘epub_download_button’: 
    _teidownload_chapter_as_epub($nid); 
    break; 
    ...
 } 
}

Figure 7

33As an example, we briefly describe the conversion to the EPUB format. Since EPUB is basically a special ZIP file, the function opens a ZIP archive and first writes some metadata to it. The content of an EPUB file is XHTML formatted by a CSS file. Since e-book readers currently do not support JavaScript, no interaction besides turning pages is possible. The user has to decide which version of the available texts he or she wants to view (see above and fig. 8). Then, the appropriate CSS file is selected and written to the ZIP archive. Finally, the body of the text, a cover image for the title page, and a table of contents for the EPUB are added. Before the file is ready for download, the node’s TEI data is again transformed with the XSLT processor and written to the archive. While the module supports conversion to EPUB and plain text (and allows downloading the original TEI file), this conversion mechanism can of course be used to cover various formats.

35We conclude the comparison of the projects in table 3, which gives an overview of the features discussed here.

Table 3

6. Conclusion and Future Work

36Our overview and comparison of tools yields a twofold result. First, it appears that tools like TEICHI or the VM provide feature sets suitable for quite specific use cases and cater to users with quite specific needs and competencies. Tools like SADE are much more flexible and adaptive and can be used for various types of projects. Second, TEICHI and the VM are quite easy to install, use, and maintain, while SADE demands considerable preliminary customization and more IT skills of administrators and/or programmers.

37At first glance, the source of the “tools paradox” mentioned earlier would seem to be that there are essentially two competing and mutually exclusive ways of broadening the user base of any publishing tool: making the tool as generic, flexible, and customizable as possible versus making it as easy as possible to use out-of-the-box. The conclusion would be that either “complexity is the price paid for generality” or that “limitation is the price paid for ease-of-use,” with both standing in the way of a widespread user base. However, the challenge to combine expressive power with simplicity of use is faced by any developer in the domains of application software or operating systems, and it marks the long-term evolution of such endeavors. The solution to this tension is a layered software architecture with a user-friendly outer shell that follows a common graphical user interface convention. In this way, all those users interested in a simple out-of-the-box solution will be provided with default features and a default configuration without compromising the overall flexibility of the software. There is no reason why frameworks for digital editions shouldn’t follow the same evolutionary path as other end-user application software. TEI is a good starting point since it separates content from appearance, the latter delegated to stylesheets. A CMS can serve as an interface between databases and programs and provide a basis on which to build further layers for customization. A modular approach allows user communities with specific needs to develop additional modules with customized feature sets without burdening editors and administrators with unnecessary complexity for features they do not need.

39We hope that TEICHI will continue to grow, offer novel features and address new application areas. The challenge is then to keep the tool simple while also offering additional features and easy customisation for advanced users. Simplicity for TEICHI means basically two things: (a) the framework must be fully functional out-of-the-box and (b) it must be easily customized. This requires integration of the tool suite into Drupal’s administration GUI and its visual theme environment, which allows for easy installation and customization. Secondly, keeping the overall design simple can be achieved by organizing the tool in modules, which allows for activating and/or customizing only those modules of the tool suite that are actually needed.