Using the TEI GitHub Repository


Contents

Using the TEI GitHub Repository

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:
Extensions
Extensions and Customizations Development
I18N
Internationalisation Development
P5
TEI P5 Guidelines and Schema
Roma
TEI-Conformant Validator (DTD, RELAX NG or W3C Schema) Creator Development
Stylesheets
TEI XSLT Stylesheets Development Module

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:
PREFIX
This is the default location under which you wish to install files locally if you use the 'install' target. By default this is: /usr
XSL
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.
ROMAOPTS
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"
DRIVER
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

check Usage: make check

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

default Usage: make

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

convert Usage: make convert

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

dtds Usage: make dtds

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

schemas Usage: make schemas

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

html-web Usage: make html-web

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

xml 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.

split 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.

clean Usage: make clean

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

install 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 PREFIX, above) .

exemplars 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 ( https://github.com/sebastianrahtz/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:
install
Installs the P4 and P5 xsl stylesheets in /usr or wherever you have set the 'PREFIX' variable at the beginning of the Makefile.
dist
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.

  1. Create and move into a directory for your TEI files
    mkdir /tmp/tei ; cd /tmp/tei
  2. Check out a copy of Stylesheets package
    git clone https://github.com/TEIC/Stylesheets.git ./Stylesheets
  3. Check out a copy of P5 package
    git clone https://github.com/TEIC/TEI.git ./TEI
  4. Check out a copy of Roma package
    git clone https://github.com/TEIC/Roma.git ./Roma
  5. Go into Stylesheets directory and install the stylesheets
    cd Stylesheets ; make PREFIX=/tmp/tei install ; cd ..
  6. Go into Roma directory and install Roma
    cd Roma ; make PREFIX=/tmp/tei install ; cd ..
  7. Go into P5 directory and install the TEI Guidelines and Schemas
    cd TEI/P5 ; make PREFIX=/tmp/tei XSL=/tmp/tei/share/xml/tei/stylesheet install ; cd ../..
  8. Go into P5 directory and create the exemplar DTDs and Schemas
    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/.


Last recorded change to this page: 2015-11-02  •  For corrections or updates, contact web@tei-c.org