Understanding the TEI Guidelines Julia Flanders Syd Bauman WARNING: XInclude processing failed — this file should not be copied or used (and is invalid) as a result.

This TEI encoded digital file is the source.

 Edit, improving many slides, but also removing most of what used to be modelling Merge customization & modelling into this file, adding info on class system and reading the Guidelines automatically converted from presentation.odd conforming to yaps.odd conforming using p2y.xslt and p2y.perl
Brief Review of a Few Important Points Define an encoding language (that is intended to be customized) Include schemas — formal rules for encoding Explanations of how to apply these rules

The outward expression of the TEI, from the users point of view, is the TEI Guidelines, which include a set of schemas, which can be thought of as formal rules for encoding documents, and a 1500-page document which explains how to apply these rules.

These Guidelines are not intended to be applied in their entirety to every document — rather, they define a markup language which can be used in both simple and complex ways, depending on the needs of the user.

The TEI can be applied in a highly constraining manner, or more loosely; it can be used in accordance with standard practices, or when necessary it can be adapted to special needs of a small group or even an individual scholar.

Customization is the mechanism that makes all of this possible.
Yes, they're big

But they are organized — they are divided: topically into chapters & modules semantically and functionally into classes pedagogically into discussion & reference

Chapters and modules

Prose of Guidelines divided into chapters; most address a specific area, topic, or discpline-specific encoding.

Those that introduce elements or attributes have an associated module.

sample modules some modules are required, providing general-purpose encoding: e.g., the core module contains most the basic elements, the header module contains most metadata elements for the teiHeader some modules provide genre- or discipline-specific elements: e.g., the verse module contains rhyme and caesura some modules provide functionality: e.g., the linking module contains markup for encoding arbitrary passages and noting links between them

The ODD source of the TEI is divided into modules, or groups of conceptually related elements, which constitute different functional components of the encoding system:

the core elements which are needed by all documents the specific modules for different genres, such as verse or drama the specific modules needed for special types of texts, such as dictionaries or manuscripts the modules needed for particular specialized functions, such as linking, or encoding figures, or expressing uncertainty
Classes

Classes are functional or semantic groups of elements.

Two kinds: elements that appear in the same place in the logical structure — e.g., model.milestoneLike contains those milestone elements used to describe the physical and typographic structure of a codex: pb, cb, lb, and milestone elements that share a common attribute — e.g., att.ascribed is the class of elements that share the who attribute, i.e. can be attributed to an individual, including change, q, and sp

Club analogy: being a member of a model class is like being a member of a workgroup: you may be called upon for certain tasks; being a member of an attr class is like being a member of a clib with member benefits (i.e., attributes)
Class constituency

Classes are composed of elements and sometimes other classes: elements and attribute classes can be members of attribute classes a given element (or attribute class) may be a member of more than one attribute class elements, model classes, or attribute classes can be members of model classes a given element (or class) may be a member of more than one model classs

Datatypes

Datatypes are constraints on (attribute) values.

May limit values to things like: a supplied list of possible values:e.g. sex of person or cert of add a user-provided list of possible values:e.g. type of div strings that conform to a specific format:e.g. when of date, extent of gap, or xml:lang

Note: word datatype is not used in the strict computer science sense
Components of the Guidelines

The TEI Guidelines comprise: a prose discussion of encoding topics; this is the main portion of Guidelines (currently 23 numbered chapters) a reference section, with structured information about each and every element, class, and datatype (appendices A, B, & C) schema fragments, which can be used to constrain your documents so that they are more likely to match the Guidelines

Don't Panic

Reference section can seem daunting — concepts are pretty simple, but there are a lot of elements and classes, their names can be puzzling, and (currently) the formatting is awful.

Let's have a look, starting with TEI website …

Bookmark this link: http://www.tei-c.org/release/doc/tei-p5-doc/en/html/.

(If you've installed TEI yourself, the Guidelines are probably in /usr/share/doc/tei-p5-doc/en/html/.)
One Document Does it All (ODD)

Remember that the TEI Guidelines consist of three interdependant interconnected parts: the main text of the Guidelines (i.e., all but appendices A, B, & C) reference documentation for each class, macro, and element schemas that constrain encoding

These are all extracted from one single source XML document, encoded in TEI using the module for tagset documentation.
ODD: generating TEI guidelines
Roma as used to generate Guidelines Illustration of inputs & outputs to Roma for building P5: input=P5 Source ODDS, output=prose guidelines, reference documentation, schemas
Customization is fundamental to the TEI No single canonical view All TEI schemas are customizations Some are common and frequently used Others are rare or unique
ODD: generating customized schema & documentation
Illustration of inputs & outputs to Roma for generating customization: input=P5 Source ODDS + user's customization ODD, output=reference docuemtation & schemas
Why customize the TEI?

Produce a schema more closely adapted to your needs: a local schema that reflects the structure of your data a community-specific schema that reflects specific methods and agreements a task-specific schema to support some particular activity

Produce documentation that matches your actual schema. (For instance compare the vanilla TEI class for bibliographic citations with the same class in our teach-basic customization)

example particular activity: data entry
What can you customize?

Customization is a process that includes:

choosing which modules to use, which not to use choosing which elements in those modules not to use choosing which attributes on those elements not to use changing the names of elements or attributes restricting the values of attributes (important!) adding new elements adding new attributes

The TEI is not used directly in tis raw form. In all cases a customized view of the TEI, or a customization is what is used.

When users want to create TEI schemas, they create an ODD customization file that lists the modules they would like to use, the specific elements they would like to add or delete, the attributes they change, etc.

It is possible to customize the TEI very radically, but resulting markup languages are not TEI conformant. E.g., one could delete every TEI element, and then add all the elements one normally finds in the Historical Event Markup Language.
What kinds of things should always be customized? Values for type attributes Values for any kind of information for which a controlled vocabulary exists
What not to customize?

In order to remain TEI conformance: Don’t remove the header! Don't remove required elements from the header! Don't duplicate things which the TEI already has provided

How do we customize?

Use Roma, the web-based interface to roma, by Sebastian Rahtz and Arno Mittelbach.

It performs two functions: front-end GUI editor for ODD files (mostly complete) front-end GUI to roma for generating schemas & reference documentation

While this customization file is not particularly hard to write by hand, creating one is made even easier by a web-based front-end-editor called Roma. Many thanks to Sebastian Rahtz with the help of Arno Mittelbach for creating this wonderful tool.

Start from Build schema (Create a new customisation by adding elements and modules to the smallest recommended schema)

modules: core header textstructure drama linking transcr delete most elements from most modules delete the key attribute from name delete most attrs from att.global and att.global.linking constrain type of div or name