TEI: Using the TEI GitHub Repository


A README file for the Text Encoding Initiative version control setup.

Born Digital.

Integrating edits suggested by LB.Rewrote substantially in the light of move from SourceForge to GitHub.Remove obsolete references to OUCS per Bug 542.Correct bad linksUpdated link to wiki6 August 2008Chris Ruotolo Fixed typo and bad link to stylesheet documentation 21 September 2007Chris Ruotolo Converted to TEI P5 19 July 2007

James Cummings Update to reflect current TEI SVN structure and makefiles

19 July 2007

James Cummings Initial composition of file.

Introduction

The TEI makes its development files openly available on https://github.com/TEIC so that users can try out the latest developments and provide feedback about how they think the TEI should develop. This document aims to give a brief introduction to using these files directly from the TEI GitHub git Repository in which they are kept. However, it is not necessary to learn how to use the Repository if you simply want to use the most stable versions of the various TEI products.

About Version Control

The Repository uses a Version Control System known as git. This tool, like its predecessor CVS (Concurrent Versions System) and SVN (Subversion), is a content versioning tool used by many software developers to keep track of changes within their source code tree. Git provides the means to store not only the current version of a file, but a record of all changes (and who made those changes) that have occurred to that file. Use of git is particularly common on projects whose development is being undertaken by those in disparate geographical locations, or with multiple developers, since it ensures that changes made by one person are not accidentally removed when another person posts their changes to the source tree.

The GitHub site provides more detailed information about Git and how to use it.

Checking files out of the Repository

To check out the contents of a TEI GitHub Repository with a simple Unix git client, enter a command like this: git clone https://github.com/TEIC/TEI.git ./TEI

This will copy all files from the TEI repository into the directory ./TEI.

You can also browse the whole Repository using GitHub’s web-based Repository viewer.

TEIC Packages

The TEIC Repository contains files which are grouped into a small number of discrete packages for release. The following packages are currently maintained:

Prerequisites for use of TEI Modules

These packages and their associated Makefiles and scripts are all developed and tested on a Debian Linux system. While they should work (possibly with customization) on other *NIX systems (including OSX), they are not designed to work on Microsoft Windows.

If you want to use the scripts provided with these packages, we recommend you to install the following additional software packages:

  • ant
  • jing
  • perl
  • saxon
  • trang
  • xmllint
  • xsltproc
  • Extensions and Customizations Development Module

    The Extensions and Customizations Development Module provides a location for dissemination of well-known Extensions and Customizations to the TEI schemas.

    None of the customizations or extensions to the TEI should be assumed to reflect the current state of the projects, but are provided as examples of how others have customized the TEI schema in the past.

    Internationalisation Development Package

    This package produces a location for the dissemination, experimentation, and development of TEI’s internationalisation efforts. Primarily, this consists of the translation of elements, attributes, and their descriptions into other languages. This allows projects to employ coders using their native language to do markup but have it easily translated back to international ‘English’ TEI. Current languages under development include: English, French, German and Spanish. However, others are planned; if you want to help out, ask about doing so on the TEI-L mailing list.

    P5 Guidelines and Schema Development Package

    This package contains the source files for the development version of the TEI Guidelines and associated schemas. Inside the TEIC/TEI repository the sources of the English chapters of the Guidelines are in P5/Source/Guidelines/en/. To allow for internationalization, if translations of the Guidelines are made available they will be located in the same place but under their ISO two-letter language code. The source files of the Guidelines also reference separate specifications of elements, attributes and classes which are maintained in a separate directory P5/Source/Specs/ with internationlization handled internally. All of these files are in the TEI ODD (One Document Does it all) format. This is a TEI format specifically intended for writing guidelines about encoding, from which schemas and reference documentation can be automatically generated.

    As part of the P5 module, a Makefile is provided to help generate HTML versions of the TEI Guidelines, create compiled schemas, and various other possibilities. There are a number of variables that one can change at the beginning of the Makefile. Some of the more important of these are:

    • This is the default location under which you wish to install files locally if you use the ‘install’ target. By default this is: /usr
    • This is the location of the XSLT stylesheets required for the transformation of ODD files. By default this points to the location of the stylesheets as installed by the TEI Debian Packages: /usr/share/xml/tei/stylesheet however, if you want to use a remote copy of the stylesheets you may wish to change this. One option is to use the stylesheets on the TEI website: http://www.tei-c.org/release/xml/tei/stylesheet/ as the value of this variable.
    • This variable is used to pass options to Roma such as the local source file for the TEI Guidelines. By default this is “--localsource=${DRIVER}.xml
    • This points to the available local source file for the TEI Guidelines. By default this is “${LANGTREE}/guidelines-${LANGUAGE}.xml“, and changing LANGTREE and LANGUAGE would allow the generation of the guidelines in different languages if the source files for those languages exist.

    The makefile has a number of requirements, these include internet access (or a local copy of the stylesheets), and up-to-date versions of the ant, perl, jing, trang, saxon, xmllint and xsltproc programs. If you do not have these installed then many of the make targets will not work. Fortunately, there is a target which will check to make sure you have these installed: make check. Some of the more important targets are listed below:

      Makefile Targets

    • Usage: make check

      This target checks to see whether you have ant perl, jing, trang, xmllint, saxon, and xsltproc installed.

    • Usage: make

      This is the default target and creates the TEI P5 schemas in RELAX NG & DTD and the HTML version of the Guidelines.

    • Usage: make convert

      This target creates the TEI P5 schemas in RELAX NG & DTD.

    • Usage: make dtds

      This target creates DTDs for TEI P5 in the DTD/ directory.

    • Usage: make schemas

      This target creates RELAX NG Schemas for TEI P5 in the Schema/ directory.

    • Usage: make html-web

      This target creates an HTML version of the TEI Guidelines in the Guidelines/ directory.

    • Usage: make xml

      This target creates a TEI Lite (P5) XML version of the Guidelines as Guidelines.xml in the current directory (i.e., P5/) as well as also making the exemplars discussed below.

    • Usage: make split

      This target creates a set of TEI P5 ODD files, with entities resolved, that are a version of the Guidelines split into chapters, in the split/ directory.

    • Usage: make clean

      This target removes most of the files created by the other targets.

    • Usage: make install

      This target installs a separate local copy of the DTDs, Schema, and HTML version of the guidelines under the file path given by the PREFIX variable (see , above) .

    • Usage: make exemplars

      This target uses Roma to create the DTDs and Schemas from a number of exemplary ODD files in the Exemplars directory. The exemplars target will create DTDs, XML Schemas, and both compact and xml versions of RELAX NG Schemas for the customizations listed on the Customization page.

    Roma: TEI-Conformant Validator (DTD, RELAX NG or W3C Schema) Creator Development

    The Roma tool allows creation of TEI-Conformant Validators in the form of DTD, RELAX NG or W3C Schemas. This can be used to customize the TEI Schema by adding, removing, renaming elements and/or attributes. This can also be used to generate specialised documentation for this customization containing only the elements specified, or can be output in foreign languages if available. Roma uses TEI P5 and there is also a web interface at http://www.tei-c.org/Roma/ which allows an easy form-filling method of generating the schemas and documentation. Roma uses the ODD format as its base and so any customizations can be saved in this form for later re-use or refinement.

    TEI XSL Stylesheets Package

    This package contains the TEI XSLT Stylesheet library. The source code for the Stylesheets is available in its own repository on GitHub, TEIC/Stylesheets. The TEI Wiki provides a location for stylesheets produced by others for TEI documents.

    The TEI XSL Stylesheets enable one to transform XML documents to HTML, to LaTeX, and to XSL Formatting Objects. The latter two of these are frequently used to transform TEI XML into PDF format. The XSL FO style sheets were developed for use with PassiveTeX (, a system using XSL formatting objects to render XML to PDF via LaTeX, and have also been tested with Render X and Antenna House implementations.

    Significantly more detailed information is available concerning the TEI XSL Stylesheets on the TEI website http://www.tei-c.org/Stylesheets/ and advice is available via the TEI-L mailing list.

    The Makefile provided with the TEI XSL Stylesheets has no default make target. The most usable two make targets are:

    • Installs the P4 and P5 xsl stylesheets in /usr or wherever you have set the ‘PREFIX’ variable at the beginning of the Makefile.
    • This creates a release subdirectory of P5 files.

    Example: Installation of Stylesheets, P5, and Roma packages

    This is a step-by-step example of installation of the Stylesheets, P5, and Roma packages. This should give most people a working copy of the main TEI deliverables. These steps assume a linux system and command-line git client, and install everything in the “/tmp/tei/” directory. You should modify this to reflect where you want to put things on your particular system.

    • mkdir /tmp/tei ; cd /tmp/tei

    • git clone https://github.com/TEIC/Stylesheets.git ./Stylesheets

    • git clone https://github.com/TEIC/TEI.git ./TEI

    • git clone https://github.com/TEIC/Roma.git ./Roma

    • cd Stylesheets ; make PREFIX=/tmp/tei install ; cd ..

    • cd Roma ; make PREFIX=/tmp/tei install ; cd ..

    • cd TEI/P5 ; make PREFIX=/tmp/tei XSL=/tmp/tei/share/xml/tei/stylesheet install ; cd ../..

    • cd TEI/P5; make exemplars; cd ../..

    This should provide you with a working TEI hierarchy in /tmp/tei/ (or whatever you changed that to on each command) with the TEI P5 Guidelines and Schemas, the TEI XSL Stylesheets, and a copy of Roma. It should also leave you a copy of the schemas for the most popular TEI customizations in TEI/P5/Exemplars/.