This chapter describes the overall structure of the encoding scheme
defined by these Guidelines. It introduces the conceptual framework
within which the following chapters are to be understood, and describes
the technical means by which that conceptual framework is implemented in
SGML. It assumes some familiarity with SGML; see chapter .
The TEI encoding scheme consists of number of modules or DTD
fragments which we refer to below as tag sets.
Selected tag sets may be combined in many different ways, according to
principles described in this chapter, within the framework of the TEI
main DTD. Auxiliary tag sets are also defined for specific
purposes independent of the TEI main DTD.
The DTD fragments from which the main TEI DTD is constructed may be
classified as follows:
core DTD fragmentsbase DTD fragmentsadditional DTD fragments
The first two sections of this chapter discuss these distinctions and
list the specific tag sets included in each category. Section describes how to invoke the TEI document type
declaration, and how to specify which of the various base tag sets and
optional additional tag sets are used in a document.
The global attributes, characteristics postulated of
every element or tag in the encoding scheme, are defined in section
.
The remainder of the chapter contains a more technical description of
the SGML mechanisms used to implement the encoding scheme. It may be
skipped at a first reading, but a proper understanding of the topics
addressed here is essential for anyone planning to modify or extend the
TEI encoding scheme in any way (see also chapter ), and
also highly desirable for those wishing to take full advantage of its
modular nature. The structure of the main TEI DTD file itself is
outlined in section . The element
classes used to define smaller groups of elements and their
characteristics are described in section .
Both global attributes and element classes are implemented using SGML
parameter entities; various other uses of parameter
entities in the TEI DTDs are discussed in section .
Main and Auxiliary DTDs
These Guidelines define a large number of SGML tags for marking up
documents, all of which are formally defined within the document
type declaration (DTD) files provided by the TEI
and documented in the remainder of the present document. The tags are
grouped into tag sets or DTD fragments, each
comprising a set of declarations for tags which belong together in some
respect, typically related to their intended application area.
All tags used to transcribe documents are available for use within
the main DTD of the TEI and are defined in Parts III and
IV of these Guidelines. There are DTD fragments for prose and mixed
matter, verse and verse collections, drama, dictionaries, analysis and
interpretation of text, text criticism, etc. A full list, including the
files in which they are defined, and the rules determining their
selection and combination, is given in section .
A number of auxiliary DTDs are also defined in these
Guidelines. These are used for the encoding of ancillary descriptive
information useful when processing electronic documents. Part V of
these Guidelines describes several such auxiliary document types,
specifically:
An independent header typically describes the encoding of a
specific document, but in the case of a planned corpus or collection, it
may define a set of encoding practices common to all texts in the
collection. The other auxiliary document types provide information
likely to be relevant to many documents, rather than to individual
documents.
When individual TEI documents are exchanged between sites, they
should be accompanied by whatever auxiliary documents apply to them.
When larger groups of documents are exchanged, the relevant auxiliary
documents need be exchanged only once. For further information see
chapter .
The DTD files containing these auxiliary DTDs are:
Some of these auxiliary DTDs also make use of the core tag set
defined as part of the main TEI DTD; this is described in the relevant
chapters of part V.
Core, Base, and Additional Tag Sets
The main TEI DTD is constructed by selecting an appropriate
combination of smaller tag sets, each containing some set of tags likely
to be used together. These building blocks include:
Each tag set is contained in one or more system files, which are
defined by appropriate SGML parameter entity declarations
and invoked as a unit by appropriate SGML
parameter entity references.
A parameter entity is an SGML entity used only in
markup declarations; references to parameter entities are delimited by a
percent sign and a semicolon rather than the ampersand and colon used
for general entity references. The entity TEI.core.ent, for example, would be referred to using
the string %TEI.core.ent;. Parameter entities can also be
used to control the inclusion or exclusion of marked
sections of the document or DTD; the TEI DTD uses marked
sections to handle the selection of different base and additional tag
sets.
Several such declarations may be needed to invoke all parts of a given
tag set, since as well as defining elements or attributes, a tag set may
(for example) add new items to the set of global attributes or add
classes to the system of element classes. Consistent naming principles
are applied throughout the TEI scheme for these and other entities.
Thus, assuming a tag set named xxx, the following parameter entities may be
encountered:
Few tag sets declare all of these entities; only those actually used are
declared.
The interpretation of the parameter entity declarations, and the
inclusion of the appropriate tag sets, are handled by a single
driver file for the main TEI DTD. This file,
tei2.dtd, is described in detail below in
section . The remainder of the present section
identifies the files in which each tag set is contained, and the
parameter entities associated with them.
The Core Tag Sets
Two core tag sets are always included in every
invocation of the main TEI DTD. The tags and attributes that they
contain are therefore available to any TEI document. The parameter
entities used for this purpose, and the files they refer to, are:
Together with these tag sets, part II also documents a tag set for
default text structure and front and back matter. This tag set is
embedded by the base tag set selected, and may vary with the base; it is
therefore described in the next section.
The Base Tag Sets
The base tag sets are those which define the basic building blocks of
different text types. The basic structures of verse (line, stanza,
canto, etc.), for example, are not those of prose (paragraph, section,
chapter, etc.), while dictionaries use yet another set of basic
structures. Each base corresponds to one chapter of Part III of this
document.
In general, exactly one base tag set must be selected for any
TEI-conformant document. Errors will result if none, or more than one,
is selected, because the same elements may be differently defined in
different base tag sets. For documents which mingle structurally
dissimilar elements and require elements from more than one base,
however, either the mixed base or the general
base may be used; see section .
These bases require the encoder to specify which of the other bases are
to be combined.
The encoder selects a base tag set by declaring the appropriate SGML
parameter entity with the replacement text INCLUDE.
To invoke the base tag set for prose, for example, the encoder must
ensure that the DTD subset in the document contains the declaration:
]]>
The entities used to select the different base tag sets, and the
files containing the SGML declarations for each base, are listed below.
As shown in the list, each base tag set is normally contained in one
or two system files: a required one (with the extension
dtd) defining the elements in the tag set and their
attributes, and an optional one (with the file extension
ent) defining any global attributes or specialized
element classes enabled by that tag set. The parameter entities for
these files have the same name as the enabling parameter entity for the
base, with the suffixes ent and dtd
respectively: the prose base, for example, is enabled by declaring the
parameter entity TEI.prose as INCLUDE; this in turn enables declarations of TEI.prose.ent and TEI.prose.dtd
as the system files teipros2.ent and
teipros2.dtd. For further details, see
section .
Most base tag sets (but not necessarily all) embed common definitions
of text structure, front matter, and back matter, by referring to three
standard parameter entities; these are:
These default-structure tags are documented in chapter .
The Additional Tag Sets
The additional tag sets define optional tags required by different
encoders for different types of analysis and processing; each
corresponds to a chapter in part IV of this document. In any TEI
encoding, any or all of these additional tag sets may be made available,
as they are all compatible with each other and with every base tag set.
They are invoked in the same way as base tag sets, by defining the
appropriate parameter entity as INCLUDE; the
relevant parameter entities, and the files containing the additional tag
sets, are these:
Like the base tag sets, the additional tag sets are each contained in
one or two system files: a required one (with the file extension
dtd) defining the elements in the tag set and their
attributes, and an optional one (with the file extension
ent) defining any global attributes or specialized
element classes enabled by that tag set. The parameter entities for
these files have the same name as the enabling parameter entity for the
tag set, with the suffixes ent and dtd
respectively: the additional tag set for linking, segmentation, and
alignment, for example, is enabled by declaring the parameter entity
TEI.linking as INCLUDE;
this in turn
enables declarations of TEI.linking.ent and
TEI.linking.dtd as the system files
teilink2.ent and
teilink2.dtd.
User-Defined Tag Sets
As described in chapter , users may modify the markup
language defined here by renaming elements, suppressing elements, adding
new elements, or modifying element or attribute-list declarations. In
general, local modifications will be most conveniently grouped into two
files: one containing the local modifications to parameter entities
used in the DTDs, and the other containing new or modified
declarations of elements and their attributes. These files will be
embedded in the TEI DTD if they are associated with the following two
parameter entities:
In some cases, users may wish to provide completely new base or
additional tag sets, to be invoked in the same way as those defined in
this document; such tag sets should also be divided into
entity files and DTD files in
the same way as the standard tag sets. Such modifications should be
undertaken only with a thorough understanding of the interface among
core, base, and additional tag sets as documented in the final sections
of this chapter; see in particular section .
Further recommendations for the creation of user-defined extension or
modification are provided in chapters and .
Invocation of the TEI DTD
Like any other SGML document, a TEI document must begin with a
document type definition (DTD). Local systems may allow the DTD to be
implicit, but for interchange purposes it must be
explicit. Because of its highly modular nature, it may in any case be
desirable for the component parts of the TEI DTD to be made explicit
even for local processing.
The simplest version of the TEI DTD names the main TEI DTD file as
an external file, and specifies a single base tag set for use in the document,
using the parameter entity names specified in section . For example, a document using the base tag set for prose
will begin with a document type declaration something like this:
]>
]]>
A document using the base tag set for drama will define a different
parameter entity:
]>
]]>
If one or more of the additional tag sets described in
Part IV are to be used, they are invoked in the same way as the base tag
set. A document using the base tag set for prose, with the additional
tag sets for text criticism and for linking, segmentation, and
alignment, for example, will begin with a document type declaration
something like this:
]>
]]>
If local modifications are used, they may be stored in separate
files and pointed to using the parameter entities TEI.extensions.ent and TEI.extensions.dtd. If such local modifications are
added to the example just given, this is the result:
]>
]]>
If the document requires tags which are defined in different base
tag sets (e.g. prose and drama) or embeds smaller texts which use
different base tag sets, then one of the mixed-type bases must be used.
Their proper invocation is described below in section .
Combining TEI Base Tag Sets
The TEI DTD has been designed to simplify the task of choosing an
appropriate set of tags for the text in hand. The core tag set includes
tags appropriate to the majority of simple tagging requirements for
prose, verse and drama, irrespective of the base tag set chosen. For
more detailed tagging, the encoder may choose the prose base for prose
texts, the verse base for verse, and so on.
In discussing these base tag sets elsewhere in these Guidelines, it
is generally assumed for clarity of exposition that a text will fall
into one, not several, of these types. It is not uncommon, however, for
a text to combine prose and verse, or other forms treated by the TEI as
different bases. Examples include:
when the text is a collection of other texts, which do not all use
the same base: e.g. an anthology of prose, verse, and dramawhen the text contains other smaller, embedded texts: e.g. a poem
or song included in a prose narrativewhen some sections of the text are written in one form, and others
in a different form: e.g. a novel where some chapters are in prose,
others take the form of dictionary entries and still others the form of
scenes in a playwhen the text moves back and forth among forms not between
sections but within a single section: e.g. mixed prose-and-verse forms
like many pastorals or like some portions of the Poetic Edda
The TEI DTD provides the following mechanisms to handle these cases:
a definition of a corpus or collection as a series of
tei.2
documents, sharing a common TEI header (see chapter )a definition of composite texts which comprise front matter, a
group or several possibly nested groups of collected texts,
themselves possibly composite (see section )a notion of embedded text
which allows one text to be embedded within another (that is,
text is defined as a component-level element, as described
briefly at the conclusion of section )
Whichever mechanism is adopted, if the whole of the resulting
document is to be parseable by the main TEI DTD it may need to combine
elements from different TEI base tag sets. Two special-purpose base
tag sets are defined for this purpose:
the general base, which allows different sections of a
text to use different bases, but ensures that each section uses
only one basethe mixed base, which allows chunk- and
inter-level elements from any base to mix within any text division
When either of these combined bases is used, the
user must specify all of the other bases to be included in the mix as
well as either the general or the mixed base. This is the only
exception to the general rule that no more than one base tag set may be
enabled in a TEI document.
The following set of declarations for example allows for any mixture of
the low level structural tags defined in the prose, drama and dictionary
base tag sets:
]>
]]>
The following set of declarations has the same effect, but with the
additional restriction that each text division (i.e. each member of the
element class divn) must be homogenous with
respect to the mixture of available bases. Because in a
general base, each div of the text may use
a different base, the divisions of the text prefixed by this set of
declarations will each be composed of elements taken solely from one of
the prose, verse or dictionary base tag sets:
]>
]]>
The actual DTD fragments for the combined bases do nothing but
embed the default tag set for overall text structure.
The mixed-base tag set is in file teimix2.dtd:
%TEI.structure.dtd;
]]>
The general-base tag set is in file
teigen2.dtd:
%TEI.structure.dtd;
]]>
Global Attributes
The following attributes are defined for every TEI element.More
exactly, these are the attributes of the element class
global, to which all elements belong; for
further discussion of attribute classes and ways in which attributes
may be inherited and over-ridden, see section .
provides a unique identifier for the element bearing the ID
value.gives a number (or other label) for an element, which is
not necessarily unique within the document.indicates the language of the element content, usually
using a two- or three-letter code from ISO 639.indicates how the element in question was rendered or
presented in the source text.
Some tag sets (e.g. those for terminology, linking, and analysis)
define other global attributes; these are documented in the appropriate
chapters of Part III and Part IV. See also section .
An additional attribute, TEIform, is also defined
for every TEI element. Unlike the other attributes defined for every
element, TEIform is not defined by class global because its default value is different in
every case and must be defined individually for each element.A dummy element class TEIform is
defined in the reference section, solely for documentary purposes.
indicates the standard TEI name (generic identifier) for a
given element.
Any TEI element may be given values for id, n,
lang, rend, or TEIform, simply by
specifying values for these attributes.
The following two examples convey the same information about the text:
that the material transcribed occurs within a p element
(paragraph). They differ only in that the second provides an identifier
for the paragraph, to which other elements (e.g. notes or hypertext
links) can conveniently refer.
If to do were as easy as to know what were
good to do, chapels had been churches and poor men's cottages
princes' palaces. It is a good divine that follows his own
instructions ...
]]>
If to do were as easy as to know what were
good to do, chapels had been churches and poor men's cottages
princes' palaces. It is a good divine that follows his own
instructions ...
]]>
ID values must be legal SGML names; by default, this means they must
begin with a letter from A to Z or a to z and contain no characters
other than the letters A to Z or a to z, the digits 0 to 9, the full
stop, and the hyphen. Furthermore, by default upper and lower case
letters are not distinguished: thus, the strings a23 and
A23 are identical, and may not be used to identify two
distinct elements.
If two elements are given the same identifier, the SGML parser will
signal a syntax error. The following example, therefore, is
not valid:
What's it going to be then, eh?
There was me, that is Alex, and my three droogs,
that is Pete, Georgie, and Dim, ...
]]>
For a discussion of methods of providing unique identifiers for
elements, see section .
The n attribute allows identifying information (e.g.
chapter numbers, etc.) to be encoded even if it would not be a legal
id value. Its value may be any string of characters;
typically it is a number or other similar enumerator or label. For
example, the numbers given to the items of a numbered list may be
recorded with the n attribute; this would make it possible to
record errors in the numeration of the original, as in this list of
chapters, transcribed from a faulty original in which the number 10 is
used twice, and 11 is omitted:
About These Guidelines
A Gentle Introduction to SGML
Verse
Drama
Spoken Materials
Printed Dictionaries
]]>
The n attribute may also be used to record non-unique names
associated with elements in a text, possibly together with a unique
identifier as in the following examples:
]]>
]]>
The lang attribute indicates the language, writing system,
and character set associated with a given element and all its contents.
If it is not specified, the value is inherited from that of the
immediately enclosing element. As a rule, therefore, it is simplest to
specify the base language of the text on the tei.2 element, and
allow most elements to take the default value for lang; the
language of an element then need be explicitly specified only for
elements in languages other than the base language.
The following two encodings convey the same information about the
language of the text, since in the first the lang attributes
on the emph elements specify the same value as that on the
parent p element, while in the second they inherit that value
without specifying it.
... Both parties deprecated war, but one of
them would make war rather than let
the nation survive, and the other would accept
war rather than let it perish, and the war came.
]]>
... Both parties deprecated war, but one of
them would make war rather than let
the nation survive, and the other would accept
war rather than let it perish, and the war came.
]]>
In the following example, by contrast, the lang attribute
on the term element must be given if we wish to record the fact
that the technical terms used are Latin rather than English; no
lang attribute is needed on the q element, by
contrast, because it is in the same language as its parent. It is
strongly recommended that all language shifts in the source be
explicitly identified by use of the lang attribute, as
described in chapter .
The constitution declares that no bill of
attainder or ex post facto law shall
be passed. ...
]]>
Formally, the lang attribute is an
IDREF; a reference
to the id value of a language element in the TEI
header.SGML validation checks that all
IDREF values
exist as id values on elements somewhere in the current SGML
document. It is a requirement of the TEI scheme, not of SGML, that the
lang attribute point to a language element.
This means that each language used in the document should be declared in
the TEI header using the language element defined in section
.
The rend attribute is used to give information about the
physical presentation of the text in the source. In the following
example, it is used to indicate that both the emphasized word and the
proper name are printed in italics:
... Their motives might be
pure and pious; but he was equally alarmed by his knowledge
of the ambitious Bohemond, and
his ignorance of the Transalpine chiefs: ...
]]>
If all or most emph and name elements are rendered in
the text by italics, it will be more convenient to register that fact in
the TEI header once and for all and specify a rend value
only for any elements which deviate from the usual rendition.
The contents of the rend attribute are free text. In any
given project, encoders are advised to settle on a standard vocabulary
with which to describe typographic or manuscript rendition of the text,
and to document their usage of that vocabulary in the rendition
element of the TEI header.
The TEIform attribute is used to allow application
programs to handle TEI-encoded documents correctly even if some or all
elements have been renamed. Most users can ignore this attribute
entirely; it is only relevant when the TEI DTDs are modified. The TEIform attribute is based on the notion of
architectural forms developed for HyTime (ISO 10744).
The default value of TEIform for any element is the
generic identifier of that element, as described in this document. The
value for p is p, the value for div1 is
div1, etc. When elements are renamed, as described in
chapter , the declaration of TEIform is not
modified. If div1 is renamed chapter, for
example, the default value of TEIform remains
div1. An application program which does not recognize
the new generic identifier can check to see whether the attribute
TEIform exists, and examine its value if it does to find out
which TEI element, if any, is being used.
Modifications of DTDs, however, may involve more than simple renaming
of elements: sometimes elements are given not just new names, but
complete new definitions. In such cases, the TEIform
attribute may be used to indicate the standard TEI element
corresponding to the modified element. For example, if a local
modification of a DTD renamed the div1 element as chapter and also modified its formal declarations (e.g. to
change its content model), then the TEIform attribute on the
modified element should be given the default value div1, in order to indicate that the local chapter element is a modification of the standard TEI
div1.
When new elements are introduced, they may be identified as
specialized variants of existing TEI elements by giving them the
appropriate default value for TEIform. For example, if a
local element called quatrain were introduced, as a
specialized variant of the lg (line group) element which must
contain exactly four lines, then its declaration might give its
TEIform as lg, to signify that a
quatrain is a particular type of line group, thus:
]]>
The formal definition of the global attributes is as follows:
]]>
The TEI2.DTD File
All TEI-encoded documents use the same top-level DTD file, which
refers to a number of other DTD files, the exact set of other files
referred to depending on which base and which additional tagsets are in
use. The remainder of this chapter describes in some detail the
organization and function of this file and those it embeds; it is
necessarily of a rather technical and specialized nature.
The main TEI DTD is always invoked by specifying the file
tei2.dtd. This file:
takes care of certain necessary preliminaries:
embeds any locally defined changes to the standard TEI
parameter entities, so that local modifications can take precedence
over default declarations;declares TEI-specific keywords used in other declarations and
declares default values of IGNORE for all the
parameter entities used to select base and additional tag sets (see
section );declares parameter entities for TEI generic identifiers (by
embedding the file teigis2.ent; see section
);declares parameter entities for element classes, content models,
and global attributes (by embedding teiclas2.ent; see section );declares the top-level elements TEI.2 and
teiCorpus.2;embeds DTD files containing local modifications (if any),
the core tag sets, the base tag set, and the additional tag sets.
Structure of the TEI2.DTD File
Each parameter entity associated with a tag set controls several
marked sections in the main DTD file tei2.dtd.
If the entity has been declared in the DTD subset with the text INCLUDE, then the marked sections it controls will be
parsed; otherwise, they will be ignored. The marked sections controlled
by each entity:
declare and refer to the entity file for the tag set,
which defines its global attributes and element classesdeclare and refer to the DTD file for the tag set,
which defines its elements and their attributesdeclare the parameter entity component) in
a form suitable for texts using that base
The tei2.dtd file has the following
structure:
%TEI.elementNames;
%TEI.elementClasses;
]]>
A TEI-conformant document must use the tei2.dtd file, or one derived from it in the manner
described in chapter .
It must also specify which base and
which additional tag sets are to be invoked, using the mechanisms
described in section .
Embedding Local Modifications
As noted above in section , local modifications
to the DTD are most conveniently grouped into two files, one containing
modifications to the TEI parameter entities, and the other new or
changed declarations of elements and their attributes. These files
should be associated with the parameter entities
TEI.extensions.ent and
TEI.extensions.dtd by declarations included in
the document's DTD subset.
For example, if the relevant files are called project.ent and project.dtd, then declarations like the following
would be appropriate:
]]>
When an SGML entity is declared more than once, the first declaration
is binding and the others are ignored. The local modifications to
parameter entities should therefore be handled before the standard
parameter entities themselves are declared in tei2.dtd. The entity TEI.extensions.ent is referred to before any TEI
declarations are handled, to allow the user's declarations to take
priority. If the user does not provide a TEI.extensions.ent entity, the entity will be expanded
to the empty string.
For example the encoder might wish to add two phrase-level elements
it and bd, perhaps as synonyms for
hi rend='italics' and hi rend='bold'. As
described in chapter , this involves two distinct steps:
one to define the new elements, and the other to ensure that they are
placed into the TEI document structure at the right place. We deal with
the second first, by specifying the element class to which the new
elements should be attached. To do this, the standard parameter entity
x.phrase should be modified to include the two
new generic identifiers. The file containing local declarations of the
standard parameter entities will thus contain a declaration of the
following form:
]]>
The relevant fragment of the DTD is this:
%TEI.extensions.ent;
]]>
The second type of modification needed is most conveniently performed
after all the standard TEI parameter entities have been declared; this
allows the element declarations provided by the user to make use of the
parameter entities which define standard TEI content models and
attribute definitions. To facilitate this, the parameter entity
TEI.extensions.dtd is used to embed local element
declarations before any of the TEI tag sets are embedded by
the file tei2.dtd, but after all
the TEI element classes and other parameter entities have been declared.
The task of declaring the non-standard it and bd elements is thus simplified: they can, for example, use
the same parameter entities as the hi element. A suitable
local DTD-modifications file might look like the following (note that
the standard parameter-entity reference for phrase sequence is used):
]]>
For further examples of local modifications to both parameter
entities and element declarations, see chapter .
The relevant fragment of the DTD is this:
%TEI.extensions.dtd;
]]>
Embedding the Core Tag Sets
The core tag sets are embedded by the file tei2.dtd using the parameter entities TEI.header and TEI.core. The
relevant fragment of the DTD is this:
%TEI.header.dtd;
%TEI.core.dtd;
]]>
The default text structure tags, which are also documented as part of
the core, are embedded by the base tag set, unless the base defines its
own text structure tags; see the chapters on the individual bases.
Embedding the Base Tag Set
The tei2.dtd file embeds the appropriate
files for the base tag set previously selected by means of the parameter
entities described in section . A parameter entity
for the file containing the relevant DTD fragment is declared and
referred to inside a conditional marked section controlled by the
appropriate parameter entity. The relevant fragment of tei2.dtd is this:
%TEI.prose.dtd;
]]&nil;>
%TEI.verse.dtd;
]]&nil;>
%TEI.drama.dtd;
]]&nil;>
%TEI.spoken.dtd;
]]&nil;>
%TEI.dictionaries.dtd;
]]&nil;>
%TEI.terminology.dtd;
]]&nil;>
%TEI.general.dtd;
]]&nil;>
%TEI.mixed.dtd;
]]&nil;>
]]>
Embedding the Additional Tag Sets
The tei2.dtd file embeds the appropriate
files for any additional base tag set previously enabled by means of the
parameter entities described in section . A parameter
entity for the file containing the relevant DTD fragment is declared and
referred to, inside a conditional marked section controlled by the
appropriate parameter entity. The relevant fragment of tei2.dtd is this:
%TEI.linking.dtd;
]]&nil;>
%TEI.analysis.dtd;
]]&nil;>
%TEI.fs.dtd;
]]&nil;>
%TEI.certainty.dtd;
]]&nil;>
%TEI.transcr.dtd;
]]&nil;>
%TEI.textcrit.dtd;
]]&nil;>
%TEI.names.dates.dtd;
]]&nil;>
%TEI.nets.dtd;
]]&nil;>
%TEI.figures.dtd;
]]&nil;>
%TEI.corpus.dtd;
]]&nil;>
]]>
Element Classes
The TEI DTD contains over four hundred element types. To aid
comprehension, modularity and modification, the majority of these
elements are formally classified in some way. This section describes
the various element classes recognized in the TEI DTD.
Element classes are used to express two distinct kinds of commonality
among elements. The elements of a class may share some set of SGML
attributes, or they may appear in the same locations in the content
models of the TEI DTDs, or both. A class is known as an
a-class if its members share attributes, and as an
m-class if its members appear at the same locations in the
content models of other TEI elements. An element is said to
inherit attributes, or the ability to appear at a given
point in a document, from any classes of which it is a member. Classes
may have subclasses and superclasses, and the characteristics of a
superclass are inherited by all members of its subclasses.
Both types of element classes are represented in the TEI DTDs by
parameter entities. For other uses of parameter entities in the TEI
DTDs, see section .
This section describes the major element classes of each type
together with the formal declarations for their parameter entities,
which are contained in the file teiclas2.ent.
All element classes are documented in the alphabetical reference section
in Part VII.
Classes Which Share Attributes
An attribute class (a-class) groups together elements which share
some set of common attributes. For example, the members of the class
names are all elements which contain proper
nouns: e.g. name, placeName, or persName.
All of these elements use the same attributes (key and
reg) to record information about the referent or the
regularized form of the proper nouns. Similarly, the members of the
pointer class share a set of attributes
useful for managing cross-reference links and other pointers.Because the details of their pointing mechanism differ, the
members of the pointer class do not,
however, share their pointing attributes.
The attributes shared by the members of an a-class are defined in a
parameter entity; member elements inherit the attributes by referring to
the parameter entity within their attribute-list declaration (examples
below). This practice helps ensure that if the attribute definitions
for the class change, all members of the class will automatically
inherit the new definitions. Parameter entities used for this purpose
form their names by taking the name of the class they define and
prefixing the string a.; we refer to these entities as
a-dot entities.
For example, the declaration for the names
class includes attribute definitions for its two attributes
reg and key:
]]>
Members of the class typically inherit these definitions by referring to
a.names:
]]>
Subclasses of a-classes inherit the attributes of their superclass
similarly, by referring to the a-dot entity of the superclass in
defining their own a-dot entity. For example, the class xPointer is a subclass of the class pointer, as shown implicitly by the declaration of
its a-dot entity:
]]>
(For an explanation of the parameter entity extptr used in the above example, see section .)
The a-classes declared in the core tag sets of these Guidelines are:
All elements are considered members of the class global and thus include a reference to a.global; in their attribute definition list
declaration. Some tag sets add specialized attributes to the set of
global attributes; these additions are declared in the
ent file of each tag set, using the following
entity names. If the tag set does not define new global attributes, no
entity of this type is declared.
These entities are included in the teiclas2.ent file indirectly, when the
entity-declaration files of each tag set are embedded, as shown below in
section . For purposes of documentation, these
attributes are treated as if inherited by the class global from superclasses called
terminology, etc.,
and are documented under the class name.
One further complication to the inheritance mechanism should be
mentioned here. In rare cases, a member of an a-class may override the
definition of an inherited attribute. For example, the element
anchor inherits the global id attribute from the
class global --- as does every other element.
On anchor elements, however, id is not optional but
required. The declaration of anchor therefore does not refer
to the class global, but instead defines all
the inherited attributes explicitly, using its own declaration for
id and the default inherited declarations for the other
global attributes:
]]>
Because this declaration does not use the parameter entity a.global, clearly any change in the definition for that
entity will not be reflected in this declaration. Consequently, any
changes made to the global attributes as such will not be inherited by
the anchor element. Instead, such changes must be replicated
manually. Care must thus be taken in modifying attribute definitions
for a-classes if any members of the class override the inherited
definitions, to ensure that all members of the class really do get the
modified definitions.
]]>
Classes Used in Content Models
When the members of a class are structurally similar and can appear
at the same kinds of structural locations in the document, they are
grouped together into an m-class (or
model-class). M-classes are implemented by
defining a parameter entity for use in the formal declaration of element
content models. The parameter entity takes the name of the class it
defines, and prefixes the string m., which can be
interpreted as model or as members. The
replacement text of the entity is a list of the members of the class,
separated by |, the SGML symbol for alternation.
For each class an additional entity is defined, which also takes the
name of the class, this time prefixed by the string x.
(for extension); the default value of these x-dot entities
is always the empty string. A reference to the corresponding x-dot
entity is always included within the replacement string for each m-dot
entity. This enables an encoder to add new members to a class simply by
declaring a new value for an x-dot entity.
For example, the class bibl has the three
members bibl, bibl.full, and bibl.struct.
Its content-model entity is defined thus:
]]>
With the default value of the x-dot entity, this is the same as defining
m.bibl with the replacement text bibl | bibl.full | bibl.struct. If an encoder wishes
to add a new bibliographic element called myBib, it can
be added to the bibl class by redefining the
x-dot entity thus:
]]>
This changes the replacement text of m.bibl from
its default value to myBib | bibl | bibl.full |
bibl.struct. If more than one element is to be added to a class,
the x-dot entity for the class should be redefined as a list of the new
generic identifiers, each one (including the last) followed
by a vertical bar. The same effect could be achieved simply by
redefining the whole of the new m.bibl entity
directly, but the x-dot method requires no repetition of the already
existing members of the class and thus minimizes the chance of error.
Like a-classes, m-classes may have subclasses or superclasses. Just
as elements inherit from a class the ability to appear in certain
locations of a document (wherever the class can appear), so all members
of a subclass inherit the ability to appear wherever any superclass can
appear. Superclasses transmit their location characteristics to their
subclasses by referring, in declaring their m-dot entity, to the m-dot
entities of the subclasses.
For example, the class phrase includes the
classes data, edit,
hqphrase, loc, and
seg as members, as can be seen in the
declaration for its m-dot entity:
]]>
When the entity m.phrase is referred to in
content models, all members of all subclasses are included in the model.
The TEICLAS2.ENT File
The most important element classes used in TEI content models are
declared in the DTD file teiclas2.ent, which
is the default replacement text for the entity TEI.elementClasses and is embedded by the tei2.dtd file. These element classes are described,
and their declarations reproduced, in the following sections.
The class system is structured around the following threefold
division of elements:
Together the two sets of chunks and inter-level
elements make up the set of:
In general, the body of any text comprises a series of components,
optionally grouped into div elements.
Some elements belong to none of these classes; these include
high-level structural elements like tei.2 and
group as well as some specialized elements which appear only
within particular structures (like analytic,
monographic, and series). The majority of elements
found in normal running text, however, are assigned by the TEI DTDs to
one or the other of these classes.
Some component elements (e.g. p or
note) are common to all base tag sets, while others are unique
to individual tag sets. This distinction is reflected in the parameter
entity declarations, as shown below.
The teiclas2.ent file has the following
overall structure:
]]>
Low-Level Element Classes
The following low-level classes group together sets of semantically
or structurally similar elements. These classes may include both
elements in the core and elements declared in particular tag sets; a
reference is given at least to the relevant section on the core tags.
The following are phrase-level element classes:
The following are inter-level element classes:
The following classes of elements may appear anywhere within the
text element:
elements which convey non-textual
information about the text (meta-information, as it were)
milestone elements used in
reference systems
elements marking arbitrary spans
of text which has been added, deleted, or omitted from a transcription
These three classes together form the globincl
class, comprising elements which may appear anywhere within
the text element (because the class is used in an inclusion
exception on that element).
The entity declarations for these classes are these:
]]>
High-Level Element Classes
The following element classes are used to implement the threefold
structural distinction among phrases, chunks, and intermediate elements
discussed above in section . In this terminology,
chunks (or chunk elements are elements which
can occur only in chunk-level sequences (e.g. between but not within
paragraphs); inter-level elements can occur either within
chunks (at phrase-level) or between chunks (e.g. at paragraph-level),
and phrase-level elements can occur only at phrase level,
within chunks (e.g. within but not between paragraphs).
The element class common includes all
component-level (chunk- and inter-level) elements common to more than
one base. It is used in implementing the combined bases described in
section .
The relevant portion of the DTD looks like this:
]]>
Elements Marked for Text Type
The following element classes are used to group together
component-level elements which are allowed only in texts of a particular
type (i.e. texts using a specific base).
Declarations for these base-specific element classes are included in
the entity file of each base, which is in turn embedded by
the teiclas2.dtd file in the DTD fragment shown
below. If the tag set defines additions to the set of global
attributes, or declares a class of component-level elements unique to
the tag set, then it has an entity file which is embedded here;
otherwise not.
%TEI.verse.ent;
]]&nil;>
%TEI.drama.ent;
]]&nil;>
%TEI.spoken.ent;
]]&nil;>
%TEI.dictionaries.ent;
]]&nil;>
%TEI.terminology.ent;
]]&nil;>
%TEI.linking.ent;
]]&nil;>
%TEI.analysis.ent;
]]&nil;>
%TEI.transcr.ent;
]]&nil;>
%TEI.textcrit.ent;
]]&nil;>
%TEI.names.dates.ent;
]]&nil;>
%TEI.figures.ent;
]]&nil;>
]]>
Standard Content Models
As far as possible, the TEI DTDs use the following set of
frequently-encountered content models, to help achieve consistency among
different elements.
The relevant portion of the DTD looks like this:
]]&nil;>
]]&nil;>
]]&nil;>
]]&nil;>
]]&nil;>
]]&nil;>
]]>
Components in Mixed and General Bases
When the mixed or general base is in use, the definitions of the
entities component and
component.seq are rather more complex.
The relevant portion of the DTD is this:
]]&nil;>
]]&nil;>
]]&nil;>
]]&nil;>
]]&nil;>
]]&nil;>
]]&nil;>
]]>
Miscellaneous Content-Model Classes
The following element classes occupy specific places in content
models; some are relevant only when certain tag sets are selected
They are declared in the following DTD fragment:
]]>
Other Parameter Entities in TEI DTDs
The TEI DTDs use SGML parameter entities for several purposes:
to define sets of attributes shared by given classes of elements
to define classes of elements which can occur at the same
locations in content models
to identify what base tag set should be used for a document
to identify what additional tag sets should be included
to include or exclude the declaration of each element
to specify the name of each element
The first two applications of parameter entities are described above in
section . This chapter describes the other uses of
parameter entities in the TEI DTDs.
The parameter entities used to specify which base tag
set and which additional tag sets are to be used in a given document
are listed in section . Their default definition is
always IGNORE: the encoder selects the TEI base and additional
tag sets by declaring the appropriate parameter entities with the
entity text INCLUDE.
The DTD and entity files are listed in section ; if
the standard TEI entities are modified to point at locally developed DTD
files containing local modifications or extensions to the TEI DTDs, the
use of the standard parameter entity names ensures that the modification
will be obvious upon examination of the document's DTD.
The following entities are referred to by the main
tei2.dtd file to embed portions of the TEI DTDs
or locally developed extensions.
Inclusion and Exclusion of Elements
The TEI DTDs use marked sections and parameter entity references to
allow users to exclude the definitions of individual elements, in order
either to make the elements illegal in a document or to allow the
element to be redefined, as further described in chapter
.
Parameter entities used for this purpose have exactly the same name
as the generic identifier of the element concerned. The default
definition for these parameter entities is INCLUDE but they may
be changed to IGNORE in order to exclude the standard element and
attribute definition list declarations from the DTD.
The declarations for the element p, for example, are
preceded by a definition for a parameter entity with the name
p and contained within a marked
section whose keyword is
given as %p;:
]&nil;]>
]]>
These parameter entities are defined immediately preceding the
element whose declarations they control; because their names are
completely regular, they are not documented individually in the
reference section of this document.
Parameter Entities for Element Generic Identifiers
In the TEI DTDs, elements are not referred to directly by their
generic identifiers; instead, the DTDs refer to parameter entities which
expand to the standard generic identifiers.
This allows users to rename elements by redefining the appropriate
parameter entity (as described more fully in chapter ).
Parameter entities used for this purpose are formed
by taking the standard name (generic identifier) of the element and
attaching the string n. as a prefix. Thus the standard generic
identifiers for paragraphs, notes, and quotations, p,
note, and q are defined by declarations of the
following form:
]]>
Since by default parameter entities are case-sensitive, the specific
mix of upper and lower case letters in the standard name must be
preserved in the entity name.
The formal declarations of the parameter entities used for generic
identifiers are contained in the
file teigis2.ent; since
their names and replacement texts are fully predictable, these parameter
entities are not individually documented in the reference section of
these Guidelines.
The parameter entity TEI.elementNames is
used to embed the file teigis2.ent in the DTD.
A full set
of alternate generic identifiers can be substituted for the standard set
by defining TEI.elementNames to point at a
different
file.It is expected that after completion of the full
text of these Guidelines, the TEI will prepare alternate sets of generic
identifiers in languages other than English. It should be noted,
however, that in the interests of simplicity parameter entities are
used only for generic identifiers; attribute names, standard attribute
values, and parameter entity names are less easily modified.
Parameter Entities for TEI Keywords
The TEI uses the following parameter entities to signal
information which cannot be expressed using SGML keywords:
In addition, the parameter entities which control the selection of
base and additional tag sets may be regarded as a keyword.
The parameter entity INHERITED is used
to signal that the default value for an attribute should be inherited
from an enclosing element.
The definition for INHERITED is
the string #IMPLIED; as for all implied defaults, the application
program is responsible for deducing the default attribute value when no
value is specified in the element start-tag. Since the parameter entity
is resolved by the SGML parser, the application program will see no
difference between attributes whose default is %INHERITED and
those whose default is #IMPLIED --- information about which
attribute values are inherited and which are inferred in some other way
must be built into the application in advance.
The parameter entity ISO-date is used to
signal that
the value for an attribute should be an ISO-standard date value; in
this notation,Defined by ISO 8601: 1988,
Data elements and interchange formats --- Information
interchange --- Representation of dates and times
([Geneva]: International Organization for Standardization, 1988).
a date like September 22, 1968 would be written
1968-09-22. The parameter entity ISO-date
expands to CDATA.
The keywords controlling the selection of base and additional tag
sets (described in section ) all have the default
value IGNORE; the user can override this by a local declaration,
as described in section .
The parameter entities for TEI keywords are included in file
teikey2.dtd, which is the default replacement
text for the entity TEI.keywords and is embedded
by the file tei2.dtd.
The file teikey2.dtd has the following
contents:
]]>
The relevant portion of the main DTD looks like this:
%TEI.keywords.ent;
]]>