The UVic Image Markup Tool Project

Creating paleography exercises using the Image Markup Tool

Marjorie Burghart (EHESS, France) has created some great online self-correcting exercises designed to teach students how to read the XIIIth century account rolls of the House of Savoy. In the process, she has also created a package of materials and instructions to help others to create similar materials. Here are two examples of the exercises she has created:

• 1299-1300 : librate
• 1308 : prologue d'un compte

These are Marjorie's instructions in English and French:

• Download and install the Image Markup Tool.
• Download the paleography zip package (English or French).
• In the ./App/bin/web_view/ directory of IMT (i.e. by default in C:\Program Files\HCMC.UVIC.CA\Image Markup Tool\App\bin\web_view), rename or move the three default files web_view.xsl, web_view.css and web_view.js installed with IMT; replace them with the files with the same name you will find in the web_view folder in the zip package .
• Start IMT; you can open the example file to make tests, or the palaeography.[fr or en].xml file, which is a blank file containing all the "line" categories pre-created, and with some information in the <teiHeader> about what to write where (NB: when you open this palaeography.xml file, it will not find an image, which is normal: you have to add your own image file).
• Once you have loaded an image of a document in IMT, start creating your exercise:
  • Each line, or rubric title, or class of elements (like, for instance, punctuation marks that you want to group together) is a "category" in IMT; each word / element of the document is an "annotation" in IMT. To improve readability, the colours of the categories alternate in the example files.
    NB: to avoid having to create new categories each time, you can open a previously created exercise or the blank palaeography.xml file and choose Ctrl + M or File > New > New (with same categories).
    NB: the XSL is set not to show in the trancription and solution zone the category named "Marques" (it is meant to group elements belonging to the same class, but that are not on a single line of the text.
  • In each annotation, the most important part is the Annotation title (it is this element that is used to control the transcription and show the solution), and it needs to be the exact transcription of the corresponding area of the image.
  • In Annotation text, you normally put the same thing as in Annotation title by default, but you are free to put any text you want (eg, some comments on the shape of a letter, an abbreviation etc.); it is only shown in the pop up appearing when the user double-clicks on an area.
  • Some of the text displayed in the actual exercise, apart from the transcription and its solution, come from the <teiHeader>, and you need to edit it to complete your exercise. Open the menu TEI > Edit teiHeader (or click on the corresponding icon in the menu bar). Here is the list of elements and attributes processed by the XSL:
    • teiHeader / fileDesc / titleStmt / title: document title
    • teiHeader / fileDesc / titleStmt / principal: name of the author(s) of the transcription
    • teiHeader / fileDesc / sourceDesc / p / msDesc / msIdentifier / settlement: name of the place where the document is kept
    • teiHeader / fileDesc / sourceDesc / p / msDesc / msIdentifier / repository: name of the institution where the document is kept
    • teiHeader / fileDesc / sourceDesc / p / msDesc / msIdentifier / idno: shelfmark of the document
    • teiHeader / fileDesc / sourceDesc / p / msDesc / msIdentifier / idno/@type: (optional) series of documents to which this one belongs
    • teiHeader / encodingDesc / projectDesc / ab[@n='introduction']: your presentation of the document
• Once all the annotations have been placed on the image, generate the exercise: F6, or File > Create web view, or click on the corresponding icon of the menu bar. All the files necessary to have the exercise running are copied in the same directory ; additionally, you need to copy the gradient.png and close.gif files from the zip package to this directory too, to benefit from the full visual effects of the CSS (although the exercises work fine without that).

• télécharger et installer Image Markup Tool.
• Télécharger l'archive zip pour la paléographie (English ou Français).
• Dans le répertoire ./App/bin/web_view/ d'IMT (i.e. par défaut dans C:\Program Files\HCMC.UVIC.CA\Image Markup Tool\App\bin\web_view), renommer ou déplacer les trois fichiers par défaut web_view.xsl, web_view.css et web_view.js installés par IMT; les remplacer par les fichiers du même nom que vous trouverez dans le dossier web_view inclus dans l'archive zip.
• Lancer IMT; vous pouvez utiliser comme modèle le fichier palaeography.[fr ou en].xml, inclus dans le zip, qui est un fichier vide contenant, déjà créées, toutes les catégories "ligne" nécessaires, et des informations dans le <teiHeader> précisant quoi écrire où (NB: à l'ouverture du fichier palaeography.xml, un message d'erreur signalera que l'image est introuvable, ce qui est normal: à vous d'ajouter votre propre image de document).
• Une fois chargée une image de document dans IMT, commencez à créer votre exercice:
  • chaque ligne, ou rubrique, ou catégorie d'élément est une "catégorie" au sens d'IMT ; chaque mot / élément est une annotation in IMT. pour améliorer la visibilité, les couleurs associées aux catégories sont alternées dans l'exemple.
    NB: pour éviter d'avoir à recréer ces catégories à chaque exercice on peut ouvrir un exercice précédemment créé ou le fichier palaeography.xml et créer un projet vierge dans IMT avec les mêmes catégories : Ctrl + M ou File > New > New (with same categories).
    NB: la XSL est paramétrée pour ne pas montrer la catégorie "Marques" dans les zones de transcriotion et solution (elle sert à grouper des éléments appartenant à une même classe, mais qui ne se trouvent pas sur une même ligne du texte)
  • Dans chaque annotation, la partie la plus importante est Annotation title (c'est cet élément qui est utilisé pour le contrôle de la transcription, et pour montrer la solution), et elle doit contenir exactement la transcription de la zone correspondante de l'image.
    NB: vous pouvez entrer les caractères développés entre parenthèses, ex. : d(omi)ni; ces parenthèses seront interprétées par le code javascript, qui saura les utiliser pour corriger les réponses.
  • Dans Annotation text, dans l'"Annotation text", on met par défaut la même chose que dans le Annotation title, mais on peut ajouter ce que l'on veut (par exemple un commentaire paléographique sur la forme d'une abréviation, des lettres, etc.): cet élément est seulement utilisé dans le pop up apparaissant lorsqu'on double-clique sur une zone.
  • Certaines informations affichées dans l'exercice, en dehors de la transcription et de sa solution, proviennent du <teiHeader>, et il faut l'éditer pour que tout soit complet. Ouvrez le menu TEI > Edit teiHeader (ou cliquez sur l'icône correspondante dans la barre d'outils). Voici la liste des éléments et attributs traités par la XSL:
    • teiHeader / fileDesc / titleStmt / title: titre du document
    • teiHeader / fileDesc / titleStmt / principal: nom du ou des auteur(s) de la transcription
    • teiHeader / fileDesc / sourceDesc / p / msDesc / msIdentifier / settlement: lieu de conservation du document (ville)
    • teiHeader / fileDesc / sourceDesc / p / msDesc / msIdentifier / repository: institution où est conservé le document (nom des archives, de la bibliothèque...)
    • teiHeader / fileDesc / sourceDesc / p / msDesc / msIdentifier / idno: cote du document
    • teiHeader / fileDesc / sourceDesc / p / msDesc / msIdentifier / idno/@type: (optionnel) série à laquelle le document appartient
    • teiHeader / encodingDesc / projectDesc / ab[@n='introduction']: votre présentation du document
• Une fois que toutes les annottaions ont été placées sur l'image, générer l'exercice: F6, ou File > Create web view, ou cliquer sur l'icône correspondante de la barre d'outils. Tous les fichiers nécessaires au fonctionnement du fichier sont placés dans le même répertoire que lui ; ajouter les fichiers gradient.png et close.gif (inclus dans le zip) pour obtenir un même effet visuel optimal (toutefois, les exercices fonctionnent aussi sans ces fichiers image).