We use TEI

Appendix F: XSLT stylesheets

F.1 Introduction
F.2 XSLT for Menotic texts
F.3 Applying a stylesheet to your XML file

Version 3.0 beta

This is a preliminary version which can be changed or updated at any time.
The appendix has been revised by Beeke Stegmann.

 

F.1 Introduction

XSL (Extensible Markup Language) is a language for transforming XML documents into other XML documents or other formats such as HTML.

This page contains XSL Transformations (which we shall refer to as XSLT stylesheets) to be used with Menotic XML files in order to generate user-friendly HTML. To help users modify these stylesheets, they contain a number of comments explaining the intended effects of the stylesheet.

The XSLT stylesheets on this page are based on a first version developed by Vemund Olstad (2004). Tone Merete Bruvik, Aksis, University of Bergen, updated the stylesheet according to v. 2.0 of the handbook (2008). Haraldur Berharðsson, University of Iceland, has revised the stylesheet compatable with v. 2.0, in order to improve the display of e.g. initials (2014). Beeke Stegmann, University of Copenhagen, developed the latest version (2017), which is compatible with v. 3 of the Menota handbook and introduced substantial changes with regards to the facsimile display of XML transcriptions. Robert Kristof Paulsen, University of Bergen, also contributeted to the latest version.

All stylesheets published in this appendix are all available under a CC BY 4.0 license.

 


F.2 XSLT for Menotic texts

The Menota stylesheet converts a text encoded with <me:facs>, <me:dipl> and/or <me:norm> tags into easily readable HTML display. Over the years, the Menota stylesheet has been adjusted and expanded with the result of multiple versions of “the stylesheet”. The link below is to the latest version, which is compatible with version 3 of the Menota handbook. (For older versions click here.)

menota_xslt_3.xsl: Download link for XSLT stylesheet suited for texts encoded according to Menota 3.0 (TEI P5 conformant).

Note: Your browser may attempt to open this stylesheet if you just click on the link. In order to download it to your computer, try to right-click (on Windows) or ctrl-click (on Mac) the link instead.

Ch. F.3.2 below gives instructions for the usage of the stylesheet.

 


F.3 Applying a stylesheet to your XML file

There are different ways to apply an XSLT stylesheet to an XML document. This section explains the two methods we believe most people might use. The first option is to link to an XSLT stylesheet available online, while the second is to run the conversion locally with an XSL file that must be saved on your machine.

F.3.1 Online usage of stylesheet by means of link

In order to link to one of the online-stylesheets, one simply inserts a stylesheet processing instruction (“stylesheet link”) at the top of the XML document, i.e. in front of the root element. Such a stylesheet link looks like this:

<?xml-stylesheet type="text/xsl" href="http://www.menota.org/menota_xslt_3_facs.xsl"?>

Note: We have tested this instruction in newer versions of the Oxygen XML Editor. In our experience, it works fine in version 19 of the application, but not in older versions.

In the above shown code line (“stylesheet link”), the @href attribute takes the URL of the stylesheet in question as its value. The stylesheet link in the example links to the XSLT that will display the facsmilie level of a Menotic transcription. In order to display the diplomatic or normalised level of the XML transcription, one needs to use the respective URL ending in "dipl" or "norm" instead. Since the stylesheet is an XSL file, the @type attribute of the processing instruction must be set to “text/xsl”.

There are three options for URLs to be used, depending on the level of transcription one wishes to display. (One URL per transcription level; to be copied into XML file):

1. For display of texts encoded on the the facsimile level: http://www.menota.org/menota_xslt_3_facs.xsl
2. For display of texts encoded on the the diplomatic level: http://www.menota.org/menota_xslt_3_dipl.xsl
3. For display of texts encoded on the the normalised level: http://www.menota.org/menota_xslt_3_norm.xsl

Once you have inserted the stylesheet link with the right URL, you can apply the stylesheet, i.e. perform the transformation. Most editors have built-in functions that read such stylesheet processing instructions and execute them. In Oxygen, that function hides behind the round white button with the red tryangle “Apply Transformation Scenario(s)” (see image F.1 below). Alternatively, you can press Ctrl+Shift+T (on Windows) or Cmd+Shift+T (on Mac). If the tansformation was successful, your default internet browser will open and the transcription on the selected level should be displayed in a new window.

Fig. F.1. The button “Apply transformation scenario(s)” in Oxygen.

Please note that one needs to have internet access for the transformation to be carried out. Also, the transformation might not work, if your document is invalid (most likely, because you forgot to close an element somewhere).

F.3.2 Download and local usage of stylesheet

To employ the second transformation method, a local transformation, one needs to download the desired XSL file. While the online method uses three different links – or rather different URLs inthe same link – for the individual transcription levels, with the local transformation method one merely needs to download a single file that can produce the display of all three levels, though also only one level at a time. The respective display level is instead defined by the parameter option of the stylesheet (see Figure F.3 below).

Once you have downloaded and saved the XSLT stylesheet, most XML editors will, again, have built-in support for applying it. In particular if you want to execute a certain transformation many times, i.e. apply the same stylesheet mulitple times on one or more XML files, you might want to set up a so-called transformation scenario. In Oxygen, the function is called “Configure Transformation Scenario(s)” and hides behind the button with a grey tool and a small red trianlge (for instructions see ch. F.2.2 below). Once you have created a transformation scenario, you can associate it with any XML file and apply it over and over again, i.e. execute the transformation on any suitable XML file. In Oxygen, you apply an associated stylesheet by pressing the red triangle button “Apply transformation scenario(s)” (see image F.1) (or Ctrl+Shift+T on Windows / Cmd+Shift+T on Mac), and after successful transformation the results will be displayed in a new window in your default browser.

Note: The XML editor might be confused if you are trying to use both transformation methods at the same time. That means, you need to chose between using a stylesheet link that is written at the top of the XML file and an associated transformation scenario which is set-up through the interface of the editor (or called by means of commands). You can select and deselct transformation scenarios in the window “Configure Transforation Scenario(s)”.

To work with a downloaded XSLT stylesheet allows the user to change and customize the transformation instructions in the stylesheet. The output rules XSLT of the online method, in contrast, are not adjustable by the user.

These are five steps to how to set up a transformation scenario in Oxygen:

1. Open the window “Configure Transformation Scenario(s)” by clicking the button with the grey tool and the little red triangle (located to the right of the “Apply transformation scenario(s)” button, see picture F.1 above). Alternatively, one can press Ctrl+Shift+C (on Windows) or Cmd+Shift+C (on Mac). Press the buttom “New” at the bottom of the list and select “XML transformation with XSLT”.

2. Name your scenario (here: Menota_xslt_Beeke_norm) and choose your stylesheet (here: Menota_xslt_Beeke.xsl) in the box “XSL URL” by browsing through your files after clicking the folder button to right of the box. The contents of the box “XML URL” should be “${currentFileURL}”, which is its default value.

Fig. F.2. Create a transformation scenario in Oxygen: Name the scenario and choose the URL of the XSL file.

3. Use the parameter option to set the desired value for the display parameter (“visning”). The possible values are “facs”, “dipl” or “norm”. In the example (image F.3), the parameter has been set to “norm”, meaning that the transformation will display the transcription on the normalised level. In order to change the setting, highlight the “visning” row and press the buttom “Edit”. Save your choice, click “OK” and return to the window seen in image F.2.

Fig. F.3. Set the parameter option for the parameter “visning” in order to make the stylesheet display the transcription on the facsimile, diplomatic or normalized level.

4. Define a suitable output file and format in the “Output” tab by giving it a location and a name with the extension “.html”. Remember to also tick the box “Open in browser”, so that the output can be viewed immediately in your default browser:

Fig. F.4. Define the output file and its location for the html-file, which is the basis for what will be displayed in the browser.

5. Save and apply your configurations.

Note: If the transformation set-up or application returns errors, you might want to use a version of Saxon that is higher than v.9, e.g. “Saxon-PE 9.6.0.7”. Other potential sources of error are that the newer stylesheets operate with XSLT 2.0 (instead of XSLT 1.0), which is a value that can be manually set in the editor, or that the XML file that you are trying to transform is not valid.

Since any transformation scenario can only take one value for the parameter at a time, you might want to set up three separate scenarios for the different parameters corresponding to the three transcription levels. All three scenarios (idealy with easily distinguishable names) should then show up in your list of scenarios that first appears when you open the window “Configure transformation scenarios”. Instead of having to go in an edit a single scenario every time for the paramater it is using, having three separate scenarios allows one quickly to select the right scenario from this list and apply it to the XML file in question.


First published 2 January 2017. Last updated 29 October 2017. Webmaster.