8 Transformations

8.1 CETEIcean (javaScript)

CETEIcean (Cayless y Viglianti, 2018) is a Javascript library designed to render TEI XML in a browser. It does not use XSLT or XQuery transformations. It uses the browser and web standards such HTML, CSS and JavaScript. CETEIcean reads the XML and converts it in HTML using HTML (Custom Elements).

In this section you are learning how to transform your TEI file into a HTML that can be vizualized in a browser or published online.

In a nutshell, you need to follow these steps, detailed below:

Create a folder structure for the web page.
Download CETEIcean.
Add the following files: index.html, CETEI.js, CETEI.css, and your TEI.xml.
Modify index.html.
Run a web server (local o remote) with your my_web_folder in it.

8.1.1 Create a folder structure

Create the following folder structure somewhere in your computer. For now don’t worry about the files; just create my_web_folder and add inside other 3 folders: js, css, data.

  ├── 📂 my_web_folder/
    ├── index.html
    ├── 📂 js/
        ├── CETEI.js
    ├── 📂 css/
        ├── CETEIcean.css
    ├── 📂 data/
        ├── text1.xml

8.1.2 Create a html file

Copy these lines of html to a new file using a code editor, e.g., VSCode and save it as index.html. If you open the file in your browser, you will see the text you put in <h2>...</h2>. Save the html in your web folder (see above).

<!doctype html>
<html lang="en">
    <head>
        <title>Digital Edition</title>
        <meta charset="utf-8">
        <meta name="description" content="Digital Edition">
        <meta name="author" content="José Luis Losada Palenzuela">
    </head>
    <body>
        <h2>The poem edition</h2>
    </body>
</html>

8.1.3 Download CETEIcean

Download the CETEIcean files (js and css) from the CETEIcean github repository:

-CETEI.js

-CETEIcean.css (right click may help to save it)

Save both in the corresponding folders. You can find both files as well in TEIC/CETEIcean -> Releases -> Source Code, together with other files and documentation.

8.1.4 Modify `index.html`

In the index.html you need to link to the rest of the files and add some lines of script in order to integrate CETEIcean in the html. Open index.html in a code editor and add the following:

Link the CETEI.js library: Add the line before the ending element </head>:

<script src="js/CETEI.js"></script>

Create a container for the TEI elements. In there the CETEIcean library will add your TEI file transformed into html. Add it within the <body> element after <h2>The poem edition</h2>:

<section id="TEI"></section>

Link the CETEIcean.css stylesheet: Add the following line before the ending element </head>:

<link rel="stylesheet" type="text/css" href="css/CETEIcean.css"/>

Call the TEI xml into the container with this script. Add now your TEI file in the folder data/. You should change the file name in the example below to match the name of your file. Add everything just before the ending element </body>:

<script>            
  var CETEIcean = new CETEI()
  CETEIcean.getHTML5("data/Lope-Soneto-1965-PL.xml", function(data){document.getElementById("TEI").appendChild(data)
  });
</script>

You should end up having the following html document.

<!doctype html>
<html lang="en">

<head>
    <title>Digital Edition</title>
    <meta charset="utf-8">
    <meta name="description" content="Digital Edition">
    <meta name="author" content="José Luis Losada Palenzuela">
    
  <script src="js/CETEI.js"></script>
    <link rel="stylesheet" type="text/css" href="css/CETEIcean.css" />

</head>
<body>
    <h2>The poem edition</h2>
    <section id="TEI"></section>

    <script>
        var CETEIcean = new CETEI()
        CETEIcean.getHTML5("data/Lope-Soneto-1965-PL.xml", function (data) {
            document.getElementById("TEI").appendChild(data)
        });
    </script>
    
</body>
</html>

If you open the index.html in a browser you will see exaclty the same as before, just the text within <h2>The poem edition</h2>, in our case The poem edition, because CETEIcean needs a web server to transform the TEI into html.

8.1.5 Run a local web server

To perform the transformation with CETEIcean, a web server is needed, that is, a place to store and process web pages with a Hypertext Transfer Protocol (HTTP). Normaly this place is hosted on a remote server, so that you access it through a web address that start with http:// or https://, but it is possible to have a local web server in your computer for testing purposes. To set it up we are using the programing language python.

8.1.5.1 Command Line

Before you start, you need to be familiar with the Terminal (Mac/Linux) or Command Prompt/PowerShell (Windows). Normally we interact with the computer through cliking on icons and menus, dragging windows around, using a graphical interface. It’s possible to do it in a more direct way using a command-line interface, that is, a program (shell) where you can type commands that perfom different tasks in your machine, such as opening a file. For example, the following line (a command) opens a xml file saved in the folder Downloads with the program VSCode open Downloads/soneto.xml -a "Visual Studio Code".

If you need to know more about command-line interfaces see this lesson Introduction to the Bash Command Line (Milligan y Baker, 2014).

You find it (Mac) in: Applications -> Utilities -> Terminal. It looks like this:

8.1.5.2 Web server in your computer

Back to the local web server: you are runnin it using the command-line, the Terminal. You need to follow these steps:

Install Python or check if already installed.
Run a Python Command in my_web_folder.
Open http://localhost:8000 to see your tei web page.
Stop: Ctrl-C (Mac/Windows).

1. Install Python

If your computer is using Linux or macOS, Python should be already installed. You just need to check the version. If you are using Windows and don’t have Python available, go to python.org and install it.

Check the python version installed, typing in the terminal the following command python -V (hit enter). The result shoul be the Java version number. You will use different commands for running the server depending of the Python versions:

If you have Python 2 (I have Python 2.7.10): python -m SimpleHTTPServer 8000
If you have Python 3: python3 -m http.server --cgi 8000

2. Run a Python Command

Again in the terminal, you need now to navigate to the folder where you have put all CETEIcean files, etc. my_web_folder. To do that, type in the command cd and the path to your folder. I have named my web folder TEI_web and saved in Documents, so I type:

cd Documents/TEI_web

Optionally type the command ls to check if the files are actually there. Now, once in the right folder type in (Python 2 in my case. See above for Python 3):

python -m SimpleHTTPServer 8000

You should see something like this (with different paths depending on where you files are)

You local web server is now running in TEI_web…

3. Open your TEI web page

Open your browser (Safari, Firefox, Chrome…) and type in (or click here) http://localhost:8000. You should see the sonnet encoded in TEI in a html web page.

4. To stop it

You can stop the web server using in the Teminal Ctrl-C (Mac/Windows)

More detailed info about how to run a local web served can be found in Mozilla’s Developer site Running a simple local HTTP server and in this tutorial Using a Local Development Environment.

8.1.5.3 Publish in github

Of course, you want to share your page to the world. In order to make it accessible online, you can host it on Github. More information soon…

8.1.6 CETEIcean and Bootstrap

You don’t need to create a html page from scratch. Bootstrap is front-end framework that offers you, for example, ready-made responsive web pages for mobile devices. It comes already with different typographies, buttons or navigation. You can download the templates that come with all the css and js you need. See Bootstrap Starter templates.

In order to integrate your TEI documents, just follow the same instructions as above. We have create a web page with CETEIcean and Bootstrap using the sonnets enconded in this course Digital Edition of Sonnets. The entire page is available for you to download here

8.2 XSLT (saxon)

XSLT is a language for transforming XML documents into other formats, such as XML, HTML (for creating web pages) or plain text (extracting just the text content from your XML file).

    XML (TEI source)     ─┐                                     ┌─ HTML, XML,...
                          ├──  XSLT Processor (Saxon) ─ Output ─┤  
    XSLT (stylesheet)    ─┘                                     └─ TXT, CSV,...

With Oxygen, for example, you run XSLT transformations by using the so-called built-in transformation scenarios. XSLT stylesheets, XSLT processors, and even the programming language Java (needed for running the processors) are bundled within Oxygen.

This section guides you through the steps neccesary to have all those parts available in your machine, so that you can run the transformations using only the command line (terminal)

So you need:

Acces to the command Line (Terminal/Cmd).
Java installed.
Saxon HE (Saxon XSLT and XQuery Processor).
XSLT stylesheets

8.2.1 Java

To check if you have Java already installed open the Terminal and type: java -version. When I was writing this chapter, I had:

java version "9.0.4"
Java(TM) SE Runtime Environment (build 9.0.4+11)
Java HotSpot(TM) 64-Bit Server VM (build 9.0.4+11, mixed mode)

If it is not available in your computer, go to https://www.oracle.com/java -> Java SE Downloads -> JDK Download, and choose the installer for your operation system. Install it following the instructions. That’s it. You won’t do (directly) anything else with it.

8.2.2 Saxon HE

Saxon HE (Saxon XSLT and XQuery Processor) is an open source software developed by Saxonica (Saxon-PE and Saxon-EE are the paid versions). Go to https://sourceforge.net/projects/saxon/files/Saxon-HE/10/Java/, download the zip file and unzip it. Locate the saxon-he file with the extension .jar, saxon-he-10.5.jar (version 10, April 2021), and save it in an accesible location, for example, /Applications/saxon-he-10.5.jar. You will need to know the path to the file later on.

8.2.3 XSLT stylesheets

An XSLT file tells to the processor how to transform your TEI/XML. XSLT stylesheets need to be written according to your needs. Imagine you want to transform your encoded sonnet into a simple TXT file, extracting, so speaking, just the line verses. Using a XSLT syntax, you may write things like <xsl:for-each select="//l"> in order to select the element <l>. A XSLT Stylesheet can contain a series of instructions (templates), which select elements, rearrenge them or turn them into a web page.

To write XSLT stylesheets is somewhat a difficult task. For now, download the XSLT Stylesheets from the github repositories:

editio/xslt. Download the file versesLines.xsl. Save it together with your TEI/XML file.
TEIC/Stylesheets (TEI Consortium) -> Code -> Download ZIP. Unzip it, save the entire folder in an accesible location. Locate the file html.xsl within the hmtl folder. You will need to know the path to the file later on.
editio/tei2html⁷ -> Code -> Download ZIP. Unzip it, save the entire folder in an accesible location. Locate the file tei2html.xsl. You will need to know the path to the file later on.

8.2.4 Run the transformation

8.2.4.1 Extract the verse lines from the sonnet

You need to know:

the path to the saxon processor.
the path to your TEI/XML file.
the path to the XSLT stylesheet (versesLines.xsl).
A name for the transformed file with the extension .txt

Put in the same folder your TEI/XML file and the XSLT file, versesLines.xsl. In the terminal, you need now to navigate to the folder where you have both files. To do that, type in the command cd and the path to your folder. I have named my folder TEI_trans and saved in Documents, so I type:

cd Documents/TEI_trans

Open the Terminal and execute the following command. Have a look at the notation in the command: -s: source file; -xsl: stylesheet; -o: output. The arguments are issued by using minus signs and characters.

java -jar /Applications/saxon/saxon-he-10.5.jar -s:Lope-Soneto-1965-PL.xml -xsl:versesLines.xsl -o:Lope_Soneto_TXT.txt

You won’t see anything happening in the terminal, but the TXT file should have been created in the folder TEI_trans.

8.2.4.2 Create a HTML page (critical apparatus)

You are transforming your TEI/XML into a HTML page using the XSLT stylesheets from the TEI Consortium.

You need to know:

The path to the saxon processor.
The path to your TEI/XML file.
The path to the XSLT stylesheets (html.xsl)
A name for the transformed file with the extension .html

I have saved the entire folder from TEIC/Stylesheets in Documents/TEI_trans. Although you are adding just the path to the html.xsl, it is important to keep the file together with the whole folder because for the transformation not only html.xsl is used; internally, html.xsl calls other stylesheets.

The TEI source contains the sonnet with the two different encoded versions. The resulted HTML file will include the critical apparatus in form of a footnote.

Open the Terminal and execute the following command (have a look at the notation in the command: -s: source file; -xsl: stylesheet; -o: output):

java -jar /Applications/saxon/saxon-he-10.5.jar -s:Lope-Soneto-Readings-1617-1965.xml -xsl:Stylesheets-dev/html/html.xsl -o:Lope_Soneto_RDG_TXT.html

Again, you won’t see anything happening in the terminal, but the HTML file should have been created in the folder TEI_trans. Open it in a browser the see the result:

8.2.4.3 Create a HTML page (drama play)

You are transforming a drama play encoded in TEI/XML into a HTML page using the set of XSLT stylesheets, tei2html: see 8.2.3.

Go to project Drama Corpora Project (Dracor) https://dracor.org and download any play in XML-TEI format, i.e. La casa de Bernarda Alba by Lorca.

You need to know:

The path to the saxon processor.
The path to your TEI/XML drama file.
The path to the XSLT stylesheets (tei2html.xsl)
A name for the transformed file with the extension .html

Proceed as above.

8.3 EVT Viewer

EVT (Edition Visualization Technology) (Turco, Buomprisco, Pietro, Kenny, Masotti y Pugliese, 2014) is a tool to create web-based editions, in particular for publishing critical editions. The latest update also allows the display of interpretative and diplomatic versions accompanied by images.

In this section you are learning how to transform your TEI file into a HTML that can be vizualized in a browser or published online.

You need to follow these steps, detailed below:

download EVT Viewer.
add your TEI.xml file.
edit config.json.
Run a web server (local o remote) with your files and evt_viewer in it.

8.3.1 Download EVT Viewer and add your `TEI.xml`.

Download the last release of EVT Viewer from the github repository: evt-project/evt-viewer. Unzip it and save it in a place where you can easily locate it.

In the folder data/text copy your TEI.xml file. You will see that EVT comes with some editions samples for testing.

8.3.2 Edit config.json

In the configuration file config/config.json you need to provide the path and the name of your file. Open config.json in a code editor:

add [line 6] the name of your file: "dataUrl": "data/text/TEI.xml"
add [line 2] the name of your edition "indexTitle": "Lope de Vega's Sonnet"

It is possible also to point to an external online file: "dataUrl": "https://PathToYourEdition/edition.xml"

This is the minimum configuration to display a TEI edition with an encoded apparatus <app>, <rdg>, <lem>. You find more information about all possible parameters in the documentation: USER_README_EN.md (online), in the README.md or EVT2js-User manual.pdf (downloaded together with the last release).

8.3.3 Run a local web server

As well as CETEIcean, EVT Viewer needs a web server to transform the TEI into html. In this case, using the command line you need now to navigate to the folder where you have the EVT viewer and the asociated files (if you have not renamed it after downloading it, it may be something like evt2-beta2.01).

Once in the right folder type in python -m SimpleHTTPServer 8000 (Python 2) or python3 -m http.server --cgi 8000 (Python 3). Open your browser and type in (or click here) http://localhost:8000. You should see the your encoded file in the EVT viewer.

See all steps in the section (8.1.5).

You can see the EVT Viewer running a Lope de Vega’s example encoded with a critical apparatus in Lope de Vega’s Sonnet. You can download the TEI file used for this visualization directly from the page ⋮ open menu > Download XML (The witnesses are just as an example to show variance, but would not be considered in a real critical edition of the sonnet)

References

Cayless, Hugh, y Raffaele Viglianti (2018): “CETEIcean: TEI in the Browser”, en Balisage: The Markup Conference 2018, Washington, DC, <https://doi.org/10.4242/BalisageVol21.Cayless01>.

Milligan, Ian, y James Baker (2014): “Introduction to the Bash Command Line”, Adam Crymble (ed.), The Programming Historian, 3, <https://doi.org/10.46430/phen0037>.

Turco, Roberto Rosselli Del, Giancarlo Buomprisco, Chiara Di Pietro, Julia Kenny, Raffaele Masotti y Jacopo Pugliese (2014): “Edition Visualization Technology: A Simple Tool to Visualize TEI-based Digital Editions”, Journal of the Text Encoding Initiative, Issue 8, <https://doi.org/10.4000/jtei.1077>.

This set of useful XSLT stylesheets was forked from Jeroen Hellingman’s tei2html repository in ordet to add utf-8 encoding and a slightly different vizualization for drama.↩︎

8 Transformations

8.1 CETEIcean (javaScript)

8.1.1 Create a folder structure

8.1.2 Create a html file

8.1.3 Download CETEIcean

8.1.4 Modify index.html

8.1.5 Run a local web server

8.1.5.1 Command Line

8.1.5.2 Web server in your computer

8.1.5.3 Publish in github

8.1.6 CETEIcean and Bootstrap

8.2 XSLT (saxon)

8.2.1 Java

8.2.2 Saxon HE

8.2.3 XSLT stylesheets

8.2.4 Run the transformation

8.2.4.1 Extract the verse lines from the sonnet

8.2.4.2 Create a HTML page (critical apparatus)

8.2.4.3 Create a HTML page (drama play)

8.3 EVT Viewer

8.3.1 Download EVT Viewer and add your TEI.xml.

8.3.2 Edit config.json

8.3.3 Run a local web server

References

8.1.4 Modify `index.html`

8.3.1 Download EVT Viewer and add your `TEI.xml`.