P5: Directrices para la codificación y el intercambio de textos electrónicos

TEI: A Simple Customization¶1.2.1 A Simple Customization

This schema specification contains references to each of four modules, identified by the key attribute on the moduleRef element. The schema specification itself is also given an identifier (TEI-minimal). An ODD processor will generate an appropriate schema from this set of declarations, expressed using the XML DTD language, the ISO RELAX NG language, the W3C Schema language, or in principle any other adequately powerful schema language. The resulting schema may then be associated with the document instance by one of a number of different mechanisms, as further described in chapter v. A Gentle Introduction to XML. The start point (or root element) of document instances to be validated against the schema is specified by means of the start attribute. Further information about the processing of an ODD specification is given in 23.5 Implementation of an ODD System.

TEI: A Larger Customization¶1.2.2 A Larger Customization

These Guidelines introduce each of the modules making up the TEI scheme one by one, and therefore, for clarity of exposition, each chapter focusses on elements drawn from a single module. In reality, of course, the markup of a text will draw on elements taken from many different modules, partly because texts are heterogeneous objects, and partly because encoders have different goals. Some examples of this heterogeneity include:

• a text may be a collection of other texts of different types: for example, an anthology of prose, verse, and drama;
• a text may contain other smaller, embedded texts: for example, a poem or song included in a prose narrative;
• some sections of a text may be written in one form, and others in a different form: for example, a novel where some chapters are in prose, others take the form of dictionary entries, and still others the form of scenes in a play;
• an encoded text may include detailed analytic annotation, for example of rhetorical or linguistic features;
• an encoded text may combine a literal transcription with a diplomatic edition of the same or different sources;
• the description of a text may require additional specialized metadata elements, for example when describing manuscript material in detail.

The TEI provides mechanisms to support all of these and many other use cases. The architecture permits elements and attributes from any combination of modules to co-exist within a single schema. Within particular modules, elements and attributes are provided to support differing views of the ‘granularity’ of a text, for example:

• a definition of a corpus or collection as a series of TEI documents, sharing a common TEI header (see chapter 15 Language Corpora)
• a definition of composite texts which combine optional front- and back-matter with a group of collected texts, themselves possibly composite (see section 4.3.1 Grouped Texts)
• an element for the representation of embedded texts, where one narrative appears to ‘float’ within another (see section 4.3.2 Floating Texts)

Subsequent chapters of these Guidelines describe in detail markup constructs appropriate for these and many other possible features of interest. The markup constructs can be combined as needed for any given set of applications or project.

The TEI architecture also supports more detailed customization beyond the simple selection of modules. A schema may suppress elements from a module, suppress some of their attributes, change their names, or even add new elements and attributes. Detailed discussion of the kind of modification possible in this way is provided in 23.3 Personalization and Customization and conformance rules relating to their application are discussed in 23.4 Conformance. These facilities are available for any schema language (though some features may not be available in all languages). The ODD language also makes it possible to combine TEI and non-TEI modules into a single schema, provided that the non-TEI module is expressed using the RELAX NG schema language (see further 22.6 Combining TEI and Non-TEI Modules).

TEI: Attribute Classes¶1.3.1 Attribute Classes

An attribute class groups together elements which share some set of common attributes. Attribute classes are given names composed of the prefix att., often followed by an adjective. For example, the members of the class att.canonical have in common a key and a ref attribute, both of which are inherited from their membership in the class rather than individually defined for each element. These attributes are said to be defined by (or inherited from) the att.canonical class. If another element were to be added to the TEI scheme for which these attributes were considered useful, the simplest way to provide them would be to make the new element a member of the att.canonical class. Note also that this method ensures that the attributes in question are always defined in the same way, taking the same default values etc., no matter which element they are attached to.

Some attribute classes are defined within the tei infrastructural module and are thus globally available. Other attribute classes are specific to particular modules and thus defined in other chapters. Attributes defined by such classes will not be available unless the module concerned is included in a schema.

The attributes provided by an attribute class are those specified by the class itself, either directly, or by inheritance from another class. For example, the attribute class att.pointing.group provides attributes domains and targFunc to all of its members. This class is however a subclass of the att.pointing class, from which its members also inherit the attributes target, targetLang and evaluate. Members of the class att.pointing will thus have these three attributes, while members of the class att.pointing.group will have all five.

Note that some modules define superclasses of an existing infrastructural class. For example, the global attribute class att.divLike makes attributes org and sample available, while the att.metrical class, which is specific to the verse module, provides attributes met, real, and rhyme. Because att.metrical is defined as a superclass of att.divLike, all five of these attributes are available to elements; the declaration for att.metrical adds its three attributes to the three already defined by att.divLike when the verse module is included in a schema. If, however, this module is not included in a schema, then the att.divLike class supplies only the two attributes first mentioned.

Attributes specific to particular modules are documented along with the relevant module rather than in the present chapter. One particular attribute class, known as att.global, is common to all modules, and is therefore described in some detail in the next section. A full list of all attribute classes is given in Apéndice B Attribute Classes below.

TEI: Model Classes¶1.3.2 Model Classes

As noted above, the members of a given TEI model class share the property that they can all appear in the same location within a document. Wherever possible, the content model of a TEI element is expressed not directly in terms of specific elements, but indirectly in terms of particular model classes. This makes content models simpler and more consistent; it also makes them much easier to understand and to modify.

Like attribute classes, model 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. To some extent, the class system thus provides a way of reducing the whole TEI galaxy of elements into a tidy hierarchy. This is however not entirely the case.

In fact, the nature of a given class of elements can be considered along two dimensions: as noted, it defines a set of places where the class members are permitted within the document hierarchy; it also implies a semantic grouping of some kind. For example, the very large class of elements which can appear within a paragraph comprises a number of other classes, all of which have the same structural property, but which differ in their field of application. Some are related to highlighting, while others relate to names or places, and so on. In some cases, the ‘set of places where class members are permitted’ is very constrained: it may just be within one specific element, or one class of element, for example. In other cases, elements may be permitted to appear in very many places, or in more than one such set of places.

These factors are reflected in the way that model classes are named. If a model class has a name containing part, such as model.divPart or model.biblPart then it is primarily defined in terms of its structural location. For example, those elements (or classes of element) which appear as content of a div constitute the model.divPart class; those which appear as content of a bibl constitute the model.biblPart class. If, however, a model class has a name containing like, such as model.biblLike or model.nameLike, the implication is that its members all have some additional semantic property in common, for example containing a bibliographic description, or containing some form of name, respectively. These semantically-motivated classes often provide a useful way of dividing up large structurally-motivated classes: for example, the very general structural class model.pPart.data (‘data elements that form part of a paragraph’) has four semantically-motivated member classes (model.addressLike, model.dateLike, model.measureLike, and model.nameLike), the last of these being itself a superclass with several members.

Although most classes are defined by the tei infrastructure module, a class cannot be populated unless some other specific module is included in a schema, since element declarations are contained by modules. Classes are not declared ‘top down’, but instead gain their members as a consequence of individual elements' declaration of their membership. The same class may therefore contain different members, depending on which modules are active. Consequently, the content model of a given element (being expressed in terms of model classes) may differ depending on which modules are active.

Some classes contain only a single member, even when all modules are loaded. One reason for declaring such a class is to make it easier for a customization to add new member elements in a specific place, particularly in areas where the TEI does not make fully elaborated proposals. For example, the TEI class model.rdgLike, initially empty, is expanded by the textcrit module to include just the TEI rdg element. A project wishing to add an alternative way of structuring text-critical information could do so by defining their own elements and adding it to this class.

Another reason for declaring single-member classes is where the class members are not needed in all documents, but appear in the same place as elements which are very frequently required. For example, the specialized element g used to represent a non-Unicode character or glyph is provided as the only member of the model.gLike class when the gaiji module is added to a schema. References to this class are included in almost every content model, since if it is used at all the g must be available wherever text is available; however these references have no effect unless the gaiji module is loaded.

At the other end of the scale, a few of the classes predefined by the tei module are subsequently populated with very many members. For example, the class model.pPart.edit groups all the classes of element for simple editorial correction and transcription which can appear within a p or paragraph element. The core module alone adds more than fifty elements to this class; the namesdates module adds another twenty, as does the tagdocs module. Since the p element is one of the basic building blocks of a TEI document it is not surprising that each module will need to add elements to it. The class system here provides a very convenient way of controlling the resulting complexity. Typically, elements are not added directly to these very general classes, but via some intermediate semantically-motivated class.

Just as there are a few classes which have a single member, so there are some classes which are used only once in the TEI architecture. These classes, which have no superclass and therefore do not fit into the class hierarchy defined here, are a convenient way of maintaining elements which are highly structured internally, but which appear from the outside to be uniform objects like others at the same level.² Members of such classes can only ever appear within one element, or one class of elements. For example, the class model.addrPart is used only to express the content model for the element address; it references some other classes of elements, which can appear elsewhere, and also some elements which can only appear inside an address.

TEI: Standard Content Models¶1.4.1 Standard Content Models

As far as possible, the TEI schemas use the following set of frequently-encountered content models to help achieve consistency among different elements.

• macro.paraContent (contenido del párrafo) define el contenido de párrafos y elementos similares.
• macro.limitedContent (contenido del párrafo) define el contenido de elementos de prosa que no se usan para la transcripción de materiales existentes.
• macro.phraseSeq (secuencia sintagmática) >defince una secuencia de caracteres y elementos de tipo sintagmático.
• macro.phraseSeq.limited (secuencia de sintagma limitada) define una secuencia de caracteres y elementos de tipo sintagmático que no se usan normalmente para transcribir.
• macro.schemaPattern patrón (pattern) que permite elegir los elementos en el lenguaje elegido para el esquema.
• macro.specialPara (contenido de párrafo 'especial') define el modelo de contenido de elementos tipo notas o entradas de lista que contienen una serie de elementos a nivel de componentes que tienen la misma estructura de un párrafo con una serie de elementos a nivel sintagmático y inter-nivel.
• macro.xtext (el texto) define una secuencia de caracteres y elementos gaiji.

The present version of the TEI Guidelines includes some 552 different elements. Tabla 3 shows, in descending order of frequency, the seven most commonly used content models.

TEI: Datatype Macros¶1.4.2 Datatype Macros

The values which attributes may take in a TEI schema are defined, for the most part, by reference to a TEI datatype. Each such datatype is defined in terms of other primitive datatypes, derived mostly from W3C Schema Datatypes, literal values, or other datatypes. This indirection makes it possible for a TEI application to set constraints either globally or in individual cases, by redefining the datatype definition or the reference to it respectively. In some cases, the TEI datatype includes additional usage constraints which cannot be enforced by existing schema languages, although a TEI-compliant processor should attempt to validate them (see further discussion in chapter 23.4 Conformance).

Where literal values or name tokens are used in a datatype definition, an associated value list supplies definitions for the significance of suggested or (in the case of closed lists) all possible values.

TEI-defined datatypes may be grouped into those which define normalized values for numeric quantities, probabilities, or temporal expressions, those which define various kinds of shorthand codes or keys, and those which define pointers or links.

The following datatypes are used for attributes which are intended to hold normalized values of various kinds. First, expressions of quantity or probability:

• data.certainty define la gama de valores de atributos que exprimen un grado de certeza.
• data.probability define la gama de valores de atributos que exprimen un grado de probabilida.d
• data.numeric define la gama de valores de atributos para valores numéricos.
• data.interval defines attribute values used to express an interval value.
• data.percentage defines attribute values used to express a percentage value.
• data.count define la gama de valores de atributos para números enteros no negativos usados como un cálculo.

Examples of attributes using the data.probability datatype include degree on damage or certainty; examples of data.numeric include quantity on members of the att.measurement class or value on numeric; examples of data.count include cols on cell and table.

Next, the datatypes used for attributes which are intended to hold normalized dates or times, durations, or truth values:

• data.duration.w3c define la gama de valores de atributos disponibles para la representación de un periodo de tiempo usando tipos de datos W3C
• data.duration.iso define la gama de valores de atributos posibles para representar la duración en el tiempo usando formatos estàndards ISO 8601.
• data.temporal.w3c define la gama de valores de atributos que expresan un valor temporal del tipo fecha, hora, o combinación de ambas, de acuerdo con la especificación de W3C XML Schema Part 2: Datatypes Second Edition.
• data.temporal.iso define la gama de valores de atributos que expresan una expresión temporal como una fecha, una hora, o una combinación de estas, de acuerdo a un estándard internacional Elementos de datos y formatos de intercambio - Intercambio de información – Representación de fechas y horas.
• data.truthValue define la gama de valores de atributos usados para expresar un valor cierto.
• data.xTruthValue (extended truth value) define la gama de valores de atributos usados para expresar un valor cierto potencialmente desconocido.
• data.language define la gama de valores de atributos usados para identificar una combinación determinada de lenguaje y escritura humanos.

Note that in each of these cases the values used are those recommended by existing international standards: ISO 8601 as profiled by XML Schema Part 2: Datatypes Second Edition in the case of durations, times, and date; W3C Schema datatypes in the case of truth values; BCP 47 in the case of language; and ISO 5218 in the case of sex.

The following datatypes have more specialized uses:

• data.namespace define la gama de valores de atributos usados para indicar los nombres de los espacios en XML como establecen las recomendaciones técnicas del W3C para los http://www.w3.org/TR/1999/REC-xml-names-19990114/
• data.outputMeasurement define una gama de valores para emplearlos en la especificación de las dimensiones de un objeto que se ha de incluir in la red.
• data.pattern (regular expression pattern) define una gama de valores de atributos expresados como una expresión regular.
• data.point defines the data type used to express a point in cartesian space.
• data.pointer define una gama de valores de atributos usados para proporcionar un indicador de cualquier recurso, bien en el documento corriente o en otro.
• data.version defines the range of attribute values which may be used to specify a TEI or Unicode version number.
• data.versionNumber defines the range of attribute values used for version numbers.
• data.replacement defines attribute values which contain a replacement template.
• data.xpath defines attribute values which contain an XPath expression.

By far the largest number of TEI attributes take values which are coded values or names of some kind. These values may be constrained or defined in a number of different ways, each of which is given a different name, as follows:

• data.word define una gama de valores de atributos expresados como una única palabra o señal.
• data.text defines the range of attribute values used to express some kind of identifying string as a single sequence of unicode characters possibly including whitespace.
• data.name define la gama de valores de atributos expresados como identificador o un nombre en XML.
• data.enumerated define la gama de valores de atributos expresados como una única palabra o señal tomada de una lista de posibilidades documentadas.
• data.sex define la gama de valores de atributos usados para identificar el género humano o animal.
• data.xmlName defines attribute values which contain an XML name.

Attributes of type data.word, such as age on person, are used to supply an identifier expressed as any kind of single token or word. The TEI places a few constraints on the characters which may be used for this purpose: only Unicode characters classified as letters, digits, punctuation characters, or symbols can appear in an attribute value of this kind. Note in particular that such values cannot include whitespace characters. Legal values include cholmondeley, été, 1234, e_content, or xml:id, but not grand wazoo. Attributes of this kind are sometimes used to associate (by co-reference) elements of different types.

Where identifiers are defined externally, for example as part of a database or file system, the inability to include whitespace or other special characters in a value may be problematic. In other cases, it may also be simply more convenient to supply a short sequence of natural language words including spaces as a single value. For these reasons, we also provide a datatype data.text which does permit whitespace and indeed any other Unicode character. Legal values include cholmondeley, été, 1234, e-content, xml:id, and grand wazoo. This datatype should be used with care since XML will not normalize whitespace characters within it: for example the values n="a b" (two spaces) and n="a b" (three spaces) would be considered distinct. This case should be distinguished from that of an attribute permitting multiple values, each of which may be separated by whitespace which will be normalized (see further 22.4.5.1 Datatypes).

Attributes of type data.name are similar to those of type data.word, but with the additional constraint that they must be legal XML identifiers, as defined by the XML 1.0 specification, or successors. Hence, they may not begin with digits or punctuation characters. Legal identifiers include cholmondeley, été, e_content, or xml:id, but not grand wazoo or 1234. Attributes of this kind are typically used to represent XML element or attribute names.

Attributes of type data.enumerated, such as new on shift or evidence supplied by att.editLike, have the same definition as data.word above, with the added constraint that the word supplied is taken from a specific list of possibilities. In each case, the element or class specification which includes the definition for the attribute will also contain a list of possible values, together with a prose description of their intended significance. This list may be open (in which case the list is advisory), or closed (in which case it determines the range of legal values). In this latter case, the datatype will not be data.enumerated, but an explicit list of the possible values.

An attribute may, of course, take more than one value of a given type, for example a list of pointer values, or a list of words. In the TEI scheme, this information is regarded as a property of the datatype element used to document the attribute in question rather than as a distinct ‘datatype’. See further 22.4.5.1 Datatypes.