22 Documentation Elements
Table of contents
This chapter describes a module which may be used for the documentation of the XML elements and element classes which make up any markup scheme, in particular that described by the TEI Guidelines, and also for the automatic generation of schemas or DTDs conforming to that documentation. It should be used also by those wishing to customize or modify these Guidelines in a conformant manner, as further described in chapters 23.3 Personalization and Customization and 23.4 Conformance and may also be useful in the documentation of any other comparable encoding scheme, even though it contains some aspects which are specific to the TEI and may not be generally applicable.
An overview of the kind of processing environment envisaged for the module described by this chapter may be helpful. In the remainder of this chapter we refer to software which provides such a processing environment as an ODD processor.88 Like any other piece of XML software, an ODD processor may be instantiated in many ways: the current system uses a number of XSLT stylesheets which are freely available from the TEI, but this specification makes no particular assumptions about the tools which will be used to provide an ODD processing environment.
As the name suggests, an ODD processor uses a single XML document to generate multiple outputs. These outputs will include:
- formal reference documentation for elements, attributes, element classes, patterns, etc. such as those provided in Appendix C Elements below;
- detailed descriptive documentation, embedding some parts of the formal reference documentation, such as the tag description lists provided in this and other chapters of these Guidelines;
- declarative code for one or more XML schema languages, such as RELAX NG, W3C Schema, ISO Schematron, or DTD.
The input required to generate these outputs consists of running prose, and special purpose elements documenting the components (elements, classes, etc.) which are to be declared in the chosen schema language. All of this input is encoded in XML using elements defined in this chapter. In order to support more than one schema language, these elements constitute a comparatively high-level model which can then be mapped by an ODD processor to the specific constructs appropriate for the schema language in use. Although some modern schema languages such as RELAX NG or W3C Schema natively support self-documentary features of this kind, we have chosen to retain the ODD model, if only for reasons of compatibility with earlier versions of these Guidelines. For reasons of backwards compatibility, the ISO standard XML schema language RELAX NG (http://www.relaxng.org) may be used as a means of declaring content models and datatypes, but it is also possible to express content models using natively TEI XML constructs. We also use the ISO Schematron language to define additional constraints beyond those expressed in the content model, as further discussed in 22.5.3 Additional Constraints below.
In the TEI system, a schema is built by combining element and attribute declarations, more or less as required. Each element is documented by an appropriate specification element and has an identifier unique across the whole TEI scheme. For convenience, these specifications are grouped into a number of discrete modules, which can also be combined more or less as required. Each major chapter of these Guidelines defines a distinct module. Each module declares a number of elements specific to that module, and may also populate particular classes. All classes are available globally, irrespective of the module in which they are declared; particular modules extend the meaning of a class by adding elements or attributes to it. Wherever possible, element content models are defined in terms of classes rather than in terms of specific elements. Modules can also declare particular patterns, which act as short-cuts for commonly used content models or class references.
In the present chapter, we discuss the components needed to support this system. In addition, section 22.1 Phrase Level Documentary Elements discusses some general purpose elements which may be useful in any kind of technical documentation, wherever there is need to talk about technical features of an XML encoding such as element names and attributes. Section 22.2 Modules and Schemas discusses the elements which are used to document XML modules and their high-level components. Section 22.3 Specification Elements discusses the elements which document XML elements and their attributes, element classes, and generic patterns or macros. Finally, section 22.9 Module for Documentation Elements provides a summary overview of the elements provided by this module.
TEI: Phrase Level Documentary Elements¶22.1 Phrase Level Documentary Elements
TEI: Phrase Level Terms¶22.1.1 Phrase Level Terms
In any kind of technical documentation, the following phrase-level elements may be found useful for marking up strings of text which need to be distinguished from the running text because they come from some formal language:
- code contains literal code from some formal language such as a programming language.
lang (formal language) a name identifying the formal language in which the code is expressed - ident (identifier) contains an identifier or name for an object of some kind in a formal language. ident is used for tokens such as variable names, class names, type names, function names etc. in formal programming languages.
Like other phrase-level elements used to indicate the semantics of a typographically distinct string, these are members of the model.emphLike class. They are available anywhere that running prose is permitted when the module defined by this chapter is included in a schema.
usually cause a fatal error.</p>
If the cited phrase is a mathematical or chemical formula, the more specific formula element defined by the figures module (14.2 Formulæ and Mathematical Expressions) may be more appropriate.
A further group of similar phrase-level elements is also defined for the special case of representing parts of an XML document:
- att (attribute) contains the name of an attribute appearing within running text.
- gi (element name) contains the name (generic identifier) of an element.
- tag contains text of a complete start- or end-tag, possibly including attribute specifications, but excluding the opening and closing markup delimiter characters.
- val (value) contains a single attribute value.
These elements constitute the model.phrase.xml class, which is also a subclass of model.phrase. They are also available anywhere that running prose is permitted when the module defined by this chapter is included in a schema.
names when they appear in the text; the <gi>tag</gi> element however is used to show how a tag as
such might appear. So one might talk of an occurrence of the <gi>blort</gi> element which had been
tagged <tag>blort type='runcible'</tag>. The <att>type</att> attribute may take any name token as
value; the default value is <val>spqr</val>, in memory of its creator.</p>
Within technical documentation, it is also often necessary to provide more extended examples of usage or to present passages of markup for discussion. The following special elements are provided for these purposes:
- eg (example) contains any kind of illustrative example.
- egXML (example of XML) a single XML fragment demonstrating the use of some XML element or attribute, in which the egXML element functions as the root element.
Like the code element, the egXML element is used to mark strings of formal code, or passages of XML markup. The eg element may be used to enclose any kind of example, which will typically be rendered as a distinct block, possibly using particular formatting conventions, when the document is processed. It is a specialized form of the more general q element provided by the TEI core module. In documents containing examples of XML markup, the egXML element should be used for preference, as further discussed below in 22.4.2 Exemplification of Components, since the content of this element can be checked for well-formedness.
These elements are added to the class model.egLike when this module is included in a schema. That class is a part of the general model.inter class, thus permitting eg or egXML elements to appear either within or between paragraph-like elements.
TEI: Element and Attribute Descriptions¶22.1.2 Element and Attribute Descriptions
Within the body of a document using this module, the following elements may be used to reference parts of the specification elements discussed in section 22.3 Specification Elements, in particular the brief prose descriptions these provide for elements and attributes.
- specList (specification list) marks where a list of descriptions is to be inserted into the prose documentation.
- specDesc (specification description) indicates that a description of the specified element or class should be included at this point within a document.
atts (attributes) supplies attribute names for which descriptions should additionally be obtained.
<head>Element and Attribute Descriptions</head>
<p>Within the body of a document using this module, the following elements… <specList>
<specDesc key="specList"/>
<specDesc key="specDesc" atts="atts"/>
</specList>
</p>
<p>TEI practice recommends that a <gi>specList</gi> listing the elements… </p>
<!-- ... -->
</div>
When formatting the ptr element in this example, an ODD processor might simply generate the section number and title of the section referred to, perhaps additionally inserting a link to the section. In a similar way, when processing the specDesc elements, an ODD processor may recover relevant details of the elements being specified (specList and specDesc in this case) from their associated declaration elements: typically, the details recovered will include a brief description of the element and its attributes. These, and other data, will be stored in a specification element elsewhere within the current document, or they may be supplied by the ODD processor in some other way, for example from a database. For this reason, the link to the required specification element is always made using a TEI-defined key rather than an XML IDREF value. The ODD processor uses this key as a means of accessing the specification element required. There is no requirement that this be performed using the XML ID/IDREF mechanism, but there is an assumption that the identifier be unique.
A specDesc generates in the documentation the identifier, and also the contents of the desc child of whatever specification element is indicated by its key attribute, as in the example above. Documentation for any attributes specified by the atts attribute will also be generated as an associated attribute list.
TEI: Modules and Schemas¶22.2 Modules and Schemas
As mentioned above, the primary purpose of this module is to facilitate the documentation and creation of an XML schema derived from the TEI Guidelines. The following elements are provided for this purpose:
- schemaSpec (schema specification) generates a TEI-conformant schema and documentation for it.
- moduleSpec (module specification) documents the structure, content, and purpose of a single module, i.e. a named and externally visible group of declarations.
- moduleRef (module reference) references a module which is to be incorporated into a schema.
include supplies a list of the elements which are to be copied from the specified module into the schema being defined. except supplies a list of the elements which are not to be copied from the specified module into the schema being defined. - specGrp (specification group) contains any convenient grouping of specifications for use within the current module.
- specGrpRef (reference to a specification group) indicates that the declarations contained by the specGrp referenced should be inserted at this point.
- attRef (attribute pointer) points to the definition of an attribute or group of attributes.
- elementRef points to the specification for some element which is to be included in a schema
A module is a convenient way of grouping together element and other declarations, and of associating an externally-visible name with the resulting group. A specification group performs essentially the same function, but the resulting group is not accessible outside the scope of the ODD document in which it is defined, whereas a module can be accessed by name from any TEI schema specification. Elements, and their attributes, element classes, and patterns are all individually documented using further elements described in section 22.3 Specification Elements below; part of that specification includes the name of the module to which the component belongs.
<altIdent type="FPI">Names and Dates</altIdent>
<desc>Additional elements for names and dates</desc>
</moduleSpec>
namesdates
. An ODD processor encountering the moduleSpec element above can thus generate a schema fragment for the TEI namesdates module that includes declarations for all the elements (etc.) which reference it.In most realistic applications, it will be desirable to combine more than one module together to form a complete schema. A schema consists of references to one or more modules or specification groups, and may also contain explicit declarations or redeclarations of elements (see further 22.8.1 TEI customizations). Any combination of modules can be used to create a schema 89
A schema can combine references to TEI modules with references to other (non-TEI) modules using different namespaces, for example to include mathematical markup expressed using MathML in a TEI document. By default, the effect of combining modules is to allow all of the components declared by the constituent modules to coexist (where this is syntactically possible: where it is not—for example, because of name clashes—a schema cannot be generated). It is also possible to over-ride declarations contained by a module, as further discussed in section 22.8.1 TEI customizations
It is often convenient to describe and operate on sets of declarations smaller than the whole, and to document them in a specific order: such collections are called specGrps (specification groups). Individual specGrp elements are identified using the global xml:id attribute, and may then be referenced from any point in an ODD document using the specGrpRef element. This is useful if, for example, it is desired to describe particular groups of elements in a specific sequence. Note however that the order in which element declarations appear within the schema code generated from an ODD file element is not in general affected by the order of declarations within a specGrp.
<elementSpec ident="beetroot">
<!-- ... -->
</elementSpec>
<elementSpec ident="east">
<!-- ... -->
</elementSpec>
<elementSpec ident="rose">
<!-- ... -->
</elementSpec>
</specGrp> and two blue ones: <specGrp xml:id="BLUE">
<elementSpec ident="sky">
<!-- ... -->
</elementSpec>
<elementSpec ident="bayou">
<!-- ... -->
</elementSpec>
</specGrp>
</p>
<head>An overview of the imaginary module</head>
<p>The imaginary module contains declarations for coloured things: <specGrpRef target="#RED"/>
<specGrpRef target="#BLUE"/>
</p>
</div>
TEI: Specification Elements¶22.3 Specification Elements
The following elements are used to specify elements, classes, patterns, and datatypes:
- elementSpec (element specification) documents the structure, content, and purpose of a single element type.
- classSpec (class specification) contains reference information for a TEI element class; that is a group of elements which appear together in content models, or which share some common attribute, or both.
generate indicates which alternation and sequence instantiations of a model class may be referenced. By default, all variations are permitted. - macroSpec (macro specification) documents the function and implementation of a pattern.
- dataSpec (datatype specification) documents a datatype.
Unlike most elements in the TEI scheme, each of these ‘specification elements’ has a fairly rigid internal structure consisting of a large number of child elements which are always presented in the same order. Furthermore, since these elements all describe markup objects in broadly similar ways, they have several child elements in common. In the remainder of this chapter, we discuss first the elements which are common to all the specification elements, and then those which are specific to a particular type.
Specification elements may appear at any point in an ODD document, both between and within paragraphs as well as inside a specGrp element, but the specification element for any particular component may only appear once (except in the case where a modification is being defined; see further 22.8.1 TEI customizations). The order in which they appear will not affect the order in which they are presented within any schema module generated from the document. In documentation mode, however, an ODD processor will output the schema declarations corresponding with a specification element at the point in the text where they are encountered, provided that they are contained by a specGrp element, as discussed in the previous section. An ODD processor will also associate all declarations found with the nominated module, thus including them within the schema code generated for that module, and it will also generate a full reference description for the object concerned in a catalogue of markup objects. These latter two actions always occur irrespective of whether or not the declaration is included in a specGrp.
TEI: Common Elements¶22.4 Common Elements
This section discusses the child elements common to all of the specification elements; some of these are defined in the core module (3.3.4 Terms, Glosses, Equivalents, and Descriptions). These child elements are used to specify the naming, description, exemplification, and classification of the specification elements.
TEI: Description of Components¶22.4.1 Description of Components
- gloss identifies a phrase or word used to provide a gloss or definition for some other word or phrase.
- desc (description) contains a brief description of the object documented by its parent element, typically a documentation element or an entity.
- equiv (equivalent) specifies a component which is considered equivalent to the parent element, either by co-reference, or by external link.
uri (uniform resource identifier) references the underlying concept of which the parent is a representation by means of some external identifier filter references an external script which contains a method to transform instances of this element to canonical TEI name a single word which follows the rules defining a legal XML name (see http://www.w3.org/TR/REC-xml/#dt-name), naming the underlying concept of which the parent is a representation. - altIdent (alternate identifier) supplies the recommended XML name for an element, class, attribute, etc. in some language.
- listRef (list of references) supplies a list of significant references to places where this element is discussed, in the current document or elsewhere.
- remarks contains any commentary or discussion about the usage of an element, attribute, class, or entity not otherwise documented within the containing element.
<gloss>anonymous block</gloss>
<!--... -->
</elementSpec>
<valItem ident="susp">
<gloss>suspension</gloss>
<desc>the abbreviation provides the first letter(s) of the word or phrase, omitting the
remainder.</desc>
</valItem>
<valItem ident="contr">
<gloss>contraction</gloss>
<desc>the abbreviation omits some letter(s) in the middle.</desc>
</valItem>
<!--...-->
</valList>
Note that the gloss element is needed to explain the significance of the identifier for an item only when this is not apparent, for example because it is abbreviated, as in the above example. It should not be used to provide a full description of the intended meaning (this is the function of the desc element), nor to comment on equivalent values in other schemes (this is the purpose of the equiv element), nor to provide alternative versions of the ident attribute value in other languages (this is the purpose of the altIdent element).
<!--... -->
<desc xml:lang="en"
versionDate="2007-07-21">identifies a word or phrase as belonging to some
language other than that of the surrounding text. </desc>
<!--... -->
</elementSpec>
Where specifications are supplied in multiple languages, the elements gloss and desc may be repeated as often as needed. Each such description or gloss should carry both an xml:lang and a versionDate attribute to indicate the language used and the date on which the translated text was last checked against its source.
ident="death">
<equiv name="E69"
uri="http://cidoc.ics.forth.gr/"/>
<desc>
<!--... -->
</desc>
</elementSpec>
ns="http://www.example.com/ns/notTEI">
<equiv filter="http://www.example.com/equiv-filter.xsl"
mimeType="text/xsl" name="bold"/>
<gloss>bold</gloss>
<desc>contains a sequence of characters rendered in a bold face.</desc>
<!-- ... -->
</elementSpec>
<altIdent xml:lang="de">Abkürzung</altIdent>
<!--...-->
</elementSpec>
<attList>
<attDef mode="change" ident="url">
<altIdent>href</altIdent>
</attDef>
<!-- ... -->
</attList>
</elementSpec>
By default, the altIdent of a component is identical to the value of its ident attribute.
<!--... -->
<remarks>
<p>This element is intended for use only where no other element is available to mark the phrase
or words concerned. The global <att>xml:lang</att> attribute should be used in preference to
this element where it is intended to mark the language of the whole of some text element.</p>
<p>The <gi>distinct</gi> element may be used to identify phrases belonging to sublanguages or
registers not generally regarded as true languages.</p>
</remarks>
<!--... -->
</elementSpec>
<ptr target="#COHQHF"/>
</listRef>
TEI: Exemplification of Components¶22.4.2 Exemplification of Components
- exemplum groups an example demonstrating the use of an element along with optional paragraphs of commentary.
- eg (example) contains any kind of illustrative example.
- egXML (example of XML) a single XML fragment demonstrating the use of some XML element or attribute, in which the egXML element functions as the root element.
valid indicates the intended validity of the example with respect to a schema. source [att.global.source] specifies the source from which some aspect of this element is drawn.
The exemplum element is used to combine a single illustrative example with an optional paragraph of commentary following or preceding it. The illustrative example itself may be marked up using either the eg or the egXML element.
When, as here, an example contains valid XML markup, the egXML element should be used. In such a case, it will clearly be necessary to distinguish the markup within the example from the markup of the document itself. In an XML environment, this is easily done by using a different name space for the content of the egXML element. For example:
<p>The <gi>term</gi> element may be used to mark any technical term, thus: <egXML xmlns="http://www.tei-c.org/ns/Examples"> This <term>recursion</term> is giving me a headache.</egXML></p>
Alternatively, the XML tagging within an example may be ‘escaped’, either by using entity references to represent the opening angle bracket, or by wrapping the whole example in a CDATA marked section:
<p>The <gi>term</gi> element may be used to mark any technical term, thus: <egXML xmlns="http://www.tei-c.org/ns/Examples"> This <term>recursion</term> is giving me a headache.</egXML></p>
or, equivalently:
<p>The <gi>term</gi> element may be used to mark any technical term, thus: <egXML xmlns="http://www.tei-c.org/ns/Examples"><![CDATA[ This <term>recursion</term> is giving me a headache.]]></egXML></p>
However, escaping the markup in this way will make it impossible to validate, and should therefore generally be avoided.
If the XML contained in an example is not well-formed then it must either be enclosed in a CDATA marked section, or ‘escaped’ as above: this applies whether the eg or egXML is used. The valid attribute on egXML may be used to indicate the XML validity of the example with respect to some schema, as being valid, invalid, or feasibly valid.
The egXML element should not be used to tag non-XML examples: the general purpose eg or q elements should be used for such purposes.
TEI: Classification of Components¶22.4.3 Classification of Components
In the TEI scheme elements are assigned to one or more classes, which may themselves have subclasses. The following elements are used to indicate class membership:
- classes specifies all the classes of which the documented element or class is a member or subclass.
- memberOf specifies class membership of the documented element or class.
key specifies the identifier for a class of which the documented element or class is a member or subclass
The classes element appears within either the elementSpec or classSpec element. It specifies the classes of which the element or class concerned is a member by means of one or more memberOf child elements. Each such element references a class by means of its key attribute. Classes themselves are defined by the classSpec element described in section 22.6 Class Specifications below.
<memberOf key="model.phrase.xml"/>
</classes>
TEI: Element Specifications¶22.5 Element Specifications
The elementSpec element is used to document an element type, together with its associated attributes. In addition to the elements listed above, it may contain the following subcomponents:
- content (content model) contains the text of a declaration for the schema documented.
autoPrefix controls whether or not pattern names generated in the corresponding RELAX NG schema source are automatically prefixed to avoid potential nameclashes. - constraintSpec (constraint on schema) contains a constraint, expressed in some formal syntax, which cannot be expressed in the structural content model
scheme supplies the name of the language in which the constraints are defined Suggested values include: 1] schematron(ISO Schematron) ; 2] isoschematron(ISO Schematron) - attList contains documentation for all the attributes associated with this element, as a series of attDef elements.
org (organization) specifies whether all the attributes in the list are available (org="group") or only one of them (org="choice") - model describes the processing intended for a specified element.
behaviour names the process or function which this processing model uses in order to produce output. Suggested values include: 1] alternate; 2] anchor; 3] block; 4] body; 5] break; 6] cell; 7] cit; 8] document; 9] figure; 10] glyph; 11] graphic; 12] heading; 13] index; 14] inline; 15] link; 16] list; 17] listItem; 18] metadata; 19] note; 20] omit; 21] paragraph; 22] row; 23] section; 24] table; 25] text; 26] title
These subcomponents are discussed in the following sections.
TEI: Defining Content Models¶22.5.1 Defining Content Models
The element content may have three different kinds of content. It may express a content model directly using the TEI elements discussed in the remainder of this section. Alternatively, it may use a schema language of some kind, as defined by a pattern called macro.schemaPattern
, which is provided by the module defined in this chapter. This is discussed in section 22.5.2 RELAX NG Content Models below. As a third possibility, the legal content for an element may be specified using the valList element or dataRef elements, described in 22.5.4 Attribute List Specification below.
One or more of the following elements are typically used to define a content model:
- textNode indicates the presence of a text node in a content model
- elementRef points to the specification for some element which is to be included in a schema
- classRef points to the specification for an attribute or model class which is to be included in a schema
- macroRef points to the specification for some pattern which is to be included in a schema
- anyElement indicates the presence of any elements in a content model
In the simplest case, the content element may be empty. This implies that the element being specified is also empty.
An element may contain nothing but strings of Unicode characters. This is indicated by supplying the element textNode within the content element. An element containing a sequence of zero or more Unicode characters would match an element with this content model.
An elementRef provides the name of an element which may appear at a certain point in a content model. A classRef provides the name of a class, members of which may appear at a certain point in content model. A macroRef provides the name of a predefined macro, the expansion of which may be inserted at a certain point in a content model. The anyElement element is used in a few special cases where any element is permitted in a content model.
These elements are all members of an attribute class which provides attributes that further modify their significance as follows:
- att.repeatable supplies attributes for the elements which define component parts of a content model.
minOccurs (minimum number of occurences) indicates the smallest number of times this component may occur. maxOccurs (maximum number of occurences) indicates the largest number of times this component may occur. context supplies an XPath identifying a context within which this component of a content model must be found
Finally, two wrapper elements are provided to indicate whether the components of a content model form a sequence or an alternation:
<alternate minOccurs="0"
maxOccurs="unbounded">
<classRef key="model.gLike"/>
<textNode/>
</alternate>
</content>
<sequence>
<elementRef key="fileDesc"/>
<classRef key="model.teiHeaderPart"
minOccurs="0" maxOccurs="unbounded" expand="alternate"/>
<elementRef key="revisionDesc"
minOccurs="0"/>
</sequence>
</content>
TEI: RELAX NG Content Models¶22.5.2 RELAX NG Content Models
Alternatively, element content models may be defined using RELAX NG patterns, or by expressions in some other schema language, depending on the value of the macro.schemaPattern
pattern.
<rng:text/>
</content>
text
, using the RELAX NG namespace. This model will be copied unchanged to the output when RELAX NG schemas are being generated. When an XML DTD is being generated, an equivalent declaration (in this case (#PCDATA)
) will be output.<rng:group>
<rng:ref name="fileDesc"/>
<rng:zeroOrMore>
<rng:ref name="model.teiHeaderPart"/>
</rng:zeroOrMore>
<rng:optional>
<rng:ref name="revisionDesc"/>
</rng:optional>
</rng:group>
</content>
(fileDesc, (%model.teiHeaderPart;)*, revisionDesc?)
.The RELAX NG language does not formally distinguish element names, attribute names, class names, or macro names: all names are patterns which are handled in the same way, as the above example shows. Within the TEI scheme, however, different naming conventions are used to distinguish amongst the objects being named. Unqualified names (fileDesc
, revisionDesc
) are always element names. Names prefixed with model.
or att.
(e.g. model.teiHeaderPart and att.typed) are always class names. In DTD language, classes are represented by parameter entities (%model.teiHeaderPart;
in the above example); see further 1 The TEI Infrastructure.
TEI_ident
rather than simply ident
. Most of the time, this behaviour is entirely transparent to the user; the one occasion when it is not will be where a content model (expressed using RELAX NG syntax) needs explicitly to reference either the TEI ident or the other one. In such a situation, the autoPrefix attribute on content may be used. For example, suppose that we wish to define a content model for term which permits either a TEI ident or the ident defined by some other vocabulary. A suitable content model would be generated from the following content element: <rng:choice>
<rng:ref name="TEI_ident"/>
<rng:ref name="ident"/>
</rng:choice>
</content>
TEI: Additional Constraints¶22.5.3 Additional Constraints
In addition to the content element, a set of general constraintSpec elements can be used to express rules about the validity of an element. Like some other specification elements, they are identifiable (using the ident attribute) in order that a TEI customization may override, delete or change them individually. Each constraintSpec can be expressed in any notation which is found useful; the notation used must be recorded using the scheme attribute.
Schematron is an ISO standard (ISO/IEC 19757-3:2006) which defines a simple XML vocabulary for an ‘assertion language’, together with a RELAX NG schema to validate it. The Schematron assertion language provides a powerful way of expressing constraints on the content of any XML document in addition to those provided by other schema languages. Such constraints can be embedded within a TEI schema specification using the methods exemplified in this chapter. An ODD processor will typically process any constraintSpec elements in a TEI specification whose scheme attribute indicates that they are expressed in Schematron to create an ISO-conformant Schematron schema which may be used to validate document instances.
The TEI Guidelines include some additional constraints which are expressed using the ISO Schematron language. A conformant TEI document should respect these constraints, although automatic validation of them may not be possible for all processors. A TEI customization may likewise specify additional constraints using this mechanism. Some examples of what is possible using the Schematron language are given below.
scheme="isoschematron">
<constraint>
<s:assert test="@ref or @key or @name">One of the
attributes 'name', 'ref' or 'key' must be supplied</s:assert>
</constraint>
</constraintSpec>
<constraintSpec ident="activemutual"
scheme="isoschematron">
<constraint>
<s:report test="@active and @mutual">Only one of the
attributes @active and @mutual may be supplied</s:report>
</constraint>
</constraintSpec>
<constraintSpec ident="activepassive"
scheme="isoschematron">
<constraint>
<s:report test="@passive and not(@active)">the
attribute 'passive' may be supplied only if the attribute 'active' is supplied</s:report>
</constraint>
</constraintSpec>
scheme="isoschematron">
<constraint>
<s:ns prefix="tei"
uri="http://www.tei-c.org/ns/1.0"/>
<s:rule context="tei:div">
<s:report test="count( tei:div ) eq 1">if it contains any subdivisions, a
division must contain at least two of them</s:report>
</s:rule>
</constraint>
</constraintSpec>
scheme="isoschematron">
<constraint>
<s:assert test="tei:fileDesc/tei:titleStmt/tei:title[@type='introductory']"> an introductory component
of the title is expected </s:assert>
</constraint>
</constraintSpec>
<constraintSpec ident="maintitle"
scheme="isoschematron">
<constraint>
<s:assert test="tei:fileDesc/tei:titleStmt/tei:title[@type='main']"> a main title must be supplied
</s:assert>
</constraint>
</constraintSpec>
scheme="isoschematron">
<constraint>
<s:ns prefix="tei"
uri="http://www.tei-c.org/ns/1.0"/>
<s:pattern id="altTags">
<s:rule context="tei:figure">
<s:report test="not(tei:figDesc or tei:head)"> You should provide information in a figure from
which we can construct an alt attribute in HTML </s:report>
</s:rule>
</s:pattern>
</constraint>
</constraintSpec>
scheme="isoschematron">
<constraint>
<s:ns prefix="tei"
uri="http://www.tei-c.org/ns/1.0"/>
<s:pattern id="Tables">
<s:rule context="tei:table">
<s:assert test="tei:head">A <table> should have a caption, using a <head>
element</s:assert>
<s:report test="parent::tei:body">Do not use tables to lay out the document body</s:report>
</s:rule>
</s:pattern>
</constraint>
</constraintSpec>
scheme="SPITBOL">
<constraint> (output = leq(title,author) "title and author cannot be the same") </constraint>
</constraintSpec>
TEI: Attribute List Specification¶22.5.4 Attribute List Specification
The attList element is used to document information about a collection of attributes, either within an elementSpec, or within a classSpec. An attribute list can be organized either as a group of attribute definitions, all of which are understood to be available, or as a choice of attribute definitions, of which only one is understood to be available. An attribute list may thus contain nested attribute lists.
<!-- other attribute definitions here -->
<attList org="choice">
<attDef ident="include">
<!-- definition for the include attribute -->
</attDef>
<attDef ident="except">
<!-- definition for the except attribute -->
</attDef>
</attList>
</attList>
The attDef element is used to document a single attribute, using an appropriate selection from the common elements already mentioned and the following :
- attDef (attribute definition) contains the definition of a single attribute.
usage specifies the optionality of the attribute. - datatype specifies the declared value for an attribute, by referring to any datatype defined by the chosen schema language.
minOccurs (minimum number of occurences) indicates the minimum number of times this datatype may occur in the specification of the attribute being defined maxOccurs (maximum number of occurences) indicates the maximum number of times this datatype may occur in the specification of the attribute being defined - dataRef identifies the datatype of an attribute value, either by referencing an item in an externally defined datatype library, or by pointing to a TEI-defined data specification
- defaultVal (default value) specifies the default declared value for an attribute.
- valDesc (value description) specifies any semantic or syntactic constraint on the value that an attribute may take, additional to the information carried by the datatype element.
- valList (value list) contains one or more valItem elements defining possible values.
- valItem documents a single value in a predefined list of values.
The attList within an elementSpec is used to specify only the attributes which are specific to that particular element. Instances of the element may carry other attributes which are declared by the classes of which the element is a member. These extra attributes, which are shared by other elements, or by all elements, are specified by an attList contained within a classSpec element, as described in section 22.6 Class Specifications below.
TEI: Datatypes¶22.5.4.1 Datatypes
The ‘datatype’ (i.e. the kind of value) for an attribute may be specified using the elements datatype and dataRef. A datatype may be defined in any of the following three ways:
- by reference to an existing TEI datatype definition;
- by use of its name in the widely used schema datatype library maintained by the W3C as part of the definition of its schema language;
- by referencing its URI within some other datatype library.
The TEI defines a number of datatypes, each with an identifier beginning teidata.
, which are used in preference to the datatypes available natively from a target schema such as RELAX NG or W3C Schema since the facilities provided by different schema languages vary so widely. The TEI datatypes available are described in section 1.4.2 Datatype Specifications above. Note that each is, of necessity, mapped eventually to an externally defined datatype such as W3C Schema's text or name, possibly combined to give more expressivity, or constrained to a particular defined usage.
<dataFacet name="maxInclusive"
value="360.0"/>
<dataFacet name="minInclusive"
value="-360.0"/>
</dataRef>
<desc versionDate="2010-05-02"
xml:lang="en">specifies the destination of the reference by
supplying one or more URI References</desc>
<datatype minOccurs="1"
maxOccurs="unbounded">
<dataRef key="teidata.pointer"/>
</datatype>
</attDef>
#a #b #c
or http://example.org http://www.tei-c.org/index.xml
may be supplied. TEI: Value Specification¶22.5.4.2 Value Specification
element logically preceding this one.</valDesc>
subject headings.</valDesc>
in <title>Pollard and Redgrave</title>
</valDesc>
<desc>age in years at death</desc>
<datatype>
<dataRef key="teidata.numeric"/>
</datatype>
<constraintSpec ident="lessThan150"
scheme="isoschematron">
<constraint>
<s:assert test=". < 150"> age at death must be
a number less than 150 </s:assert>
</constraint>
</constraintSpec>
</attDef>
<altIdent xml:lang="fr">dou</altIdent>
<equiv name="unknown"/>
<gloss>dubious</gloss>
<desc>used when the application of this element is doubtful or uncertain</desc>
</valItem>
<valItem ident="req">
<gloss>required</gloss>
</valItem>
<valItem ident="rec">
<gloss>recommended</gloss>
</valItem>
<valItem ident="opt">
<gloss>optional</gloss>
</valItem>
</valList>
<desc versionDate="2005-01-14"
xml:lang="en">characterizes the movement, for example as an
entrance or exit.</desc>
<desc versionDate="2007-12-20"
xml:lang="ko">예를 들어 입장 또는 퇴장과 같은, 이동의 특성을 기술한다.</desc>
<datatype>
<dataRef key="teidata.enumerated"/>
</datatype>
<valList type="open">
<valItem ident="entrance">
<desc versionDate="2007-06-27"
xml:lang="en">character is entering the stage.</desc>
<desc versionDate="2007-12-20"
xml:lang="ko">등장인물이 무대에 등장하고 있다.</desc>
</valItem>
<valItem ident="exit">
<desc versionDate="2007-06-27"
xml:lang="en">character is exiting the stage.</desc>
<desc versionDate="2007-12-20"
xml:lang="ko">등장인물이 무대에서 퇴장하고 있다.</desc>
</valItem>
<valItem ident="onStage">
<desc versionDate="2007-07-04"
xml:lang="en">character moves on stage</desc>
<desc versionDate="2007-12-20"
xml:lang="ko">등장인물이 무대에서 이동한다.</desc>
</valItem>
</valList>
</attDef>
The valList or dataRef elements may also be used (as a child of the content element) to put constraints on the permitted content of an element, as noted at 22.5.2 RELAX NG Content Models. This use is not however supported by all schema languages, and is therefore not recommended if support for non-RELAX NG systems is a consideration.
TEI: Processing Models¶22.5.5 Processing Models
As far as possible, the TEI defines elements and their attributes in a way which is entirely independent of their subsequent processing, since its intention is to maximize the reusability of encoded documents and their use in multiple contexts. Nevertheless, it can be very useful to specify one or more possible models for such processing, both to clarify the intentions of the encoder, and to provide default behaviours for a software engineer to implement when documents conforming to a particular TEI customization are processed. To that end, the following elements may be used to document one or more processing models for a given element.
- model describes the processing intended for a specified element.
- modelGrp any grouping of model or modelSequence elements with a common output method
- modelSequence any sequence of model or modelSequence elements which is to be processed as a single set of actions
One or more of these elements may appear directly within an element specification to define the processing anticipated for that element, more specifically how it should be processed to produce the kind of output indicated by the output attribute. Where multiple such elements appear directly within an elementSpec, they are understood to document mutually exclusive processing models, possibly for different outputs or applicable in different contexts. Alternatively, the modelGrp element may be used to group alternative model elements intended for a single kind of output. The modelSequence element is provided for the case where a sequence of models is to be processed, functioning as a single unit.
A processing model suggests how a given element may be transformed to produce one or more outputs. The model is expressed in terms of behaviours and parameters, using high-level formatting concepts familiar to software engineers and web designers, such as ‘block’ or ‘inline’. As such, it has a different purpose from existing TEI mechanisms for documenting the appearance of source materials, such as the global attributes rend, rendition and style, described in sections 2.3.4.1 Rendition and 3.3.1 What Is Highlighting?. It does not necessarily describe anything present in the original source, nor does it necessarily represent its original structure or semantics. A processing model is a template description, which may be used to simplify the task of producing or customizing the stylesheets needed by a formatting engine or any other form of processor.
TEI: The TEI processing model¶22.5.5.1 The TEI processing model
The model element is used to document the processing model intended for a particular element in an abstract manner, independently of its implementation in whatever processing language is chosen. This is achieved by means of the following attributes and elements:
- model describes the processing intended for a specified element.
predicate the condition under which this model applies, given as an XPath predicate expression. behaviour names the process or function which this processing model uses in order to produce output. Suggested values include: 1] alternate; 2] anchor; 3] block; 4] body; 5] break; 6] cell; 7] cit; 8] document; 9] figure; 10] glyph; 11] graphic; 12] heading; 13] index; 14] inline; 15] link; 16] list; 17] listItem; 18] metadata; 19] note; 20] omit; 21] paragraph; 22] row; 23] section; 24] table; 25] text; 26] title output the intended output. Sample values include: 1] web; 2] print; 3] plain useSourceRendition whether to obey any rendition attribute which is present. cssClass the name of a CSS class which should be associated with this element - outputRendition describes the rendering or appearance intended for all occurrences of an element in a specified context for a specified type of output.
scope provides a way of defining ‘pseudo-elements’, that is, styling rules applicable to specific sub-portions of an element. Sample values include: 1] first-line; 2] first-letter; 3] before; 4] after
The mandatory behaviour attribute defines in broad terms how an element should be processed, for example as a block or as an inline element. The optional predicate attribute may be used to specify a subset of contexts in which this model should be applicable: for example, an element might be treated as a block element in some contexts, but not in others. The output attribute supplies a name for the output for which this model is intended, for example for screen display, for a printed reading copy, for a scholarly publication, etc. The way in which an element should be rendered is declared independently of its behaviour, using either the attribute useSourceRendition or the element outputRendition. These Guidelines recommend that outputRendition be expressed using the W3C Cascading Stylesheet Language (CSS), but other possibilities are not excluded. The particular language used may be documented by means of the styleDefDecl element described in 2.3.5 The Default Style Definition Language Declaration.
TEI: Output Rendition ¶22.5.5.2 Output Rendition
<outputRendition>font-style: italic;</outputRendition>
</model>
useSourceRendition="true"/>
useSourceRendition="true">
<outputRendition>font-style: italic;</outputRendition>
</model>
TEI: CSS Class¶22.5.5.3 CSS Class
<model predicate="label" behaviour="list"
cssClass="labeled-list">
<!-- ... -->
</model>
</elementSpec>
<!-- Preserve original rendition for tables which contain @rendition hints -->
<model predicate=".//row/@rendition or .//cell/@rendition"
behaviour="table" useSourceRendition="true"/>
<!-- Use bootstrap for default table styling -->
<model behaviour="table"
useSourceRendition="true"
cssClass="table table-hover table-bordered"/>
</elementSpec>
As discussed further below, the input data available to a processing model is by default the content of the element being processed, together with its child nodes.
TEI: Model Contexts and Outputs¶22.5.5.4 Model Contexts and Outputs
<model predicate="ancestor::p"
behaviour="inline">
<outputRendition>font-style: italic;</outputRendition>
</model>
<model behaviour="block">
<outputRendition>left-margin: 2em;</outputRendition>
</model>
</elementSpec>
When, as here, multiple behaviours are required for the same element, it will often be the case that the appropriate processing will depend on the context. It may however be the case that the choice of an appropriate model will be made on the basis of the intended output. For example, we might wish to define quite different behaviours when a document is to be displayed on a mobile device and when it is to be displayed on a desktop screen. Different behaviours again might be specified for a print version intended for the general reader, and for a print version aimed at the technical specialist.
<model behaviour="inline"
predicate="@rend='inline'">
<outputRendition>font-size: 7pt;</outputRendition>
</model>
<model behaviour="block"
predicate="@rend='block'">
<outputRendition>text-color: red;</outputRendition>
</model>
</modelGrp>
<modelGrp output="print">
<model behaviour="inline"
predicate="@rend='inline'">
<outputRendition>font-size: 12pt;</outputRendition>
</model>
<model behaviour="block"
useSourceRendition="true" predicate="@rend='block'">
<outputRendition>text-align: center;</outputRendition>
</model>
</modelGrp>
TEI: Behaviours and their parameters¶22.5.5.5 Behaviours and their parameters
In the examples above we have used without explanation or definition two simple behaviours: inline and block, but many other behaviours are possible. A list of recommended behaviour names forms part of the specification for the element model. A processing model can specify any named behaviour, some of which have additional parameters. The parameters of a behaviour resemble the arguments of a function in many programming languages: they provide names which can be used to distinguish particular parts of the input data available to the process used to implement the behaviour in question.
The following elements are used to represent and to define parameters:
- param provides a parameter for a model behaviour by supplying its name and an XPath expression identifying the location of its content.
name a name for the parameter being supplied Suggested values include: 1] alternate; 2] default; 3] height; 4] id; 5] label; 6] level; 7] link; 8] place; 9] type; 10] url; 11] width - paramList list of parameter specifications
- paramSpec supplies specification for one parameter of a model behaviour
By default, a processor implementing the TEI processing model for a particular element has available to it as input data the content of the element itself, and all of its children. One or more param elements may be supplied within a model element to specify parameters which modify this, either by selecting particular parts of the default input data, or by selecting data which would not otherwise be available. In either case, the value supplied for the parameter is given as an XPath expression, evaluated with respect to the element node being processed. An arbitrary name (defined in the corresponding paramSpec) is also supplied to a processor to identify each parameter.
<model behaviour="link">
<param name="uri" value="@target"/>
<param name="content" value="."/>
</model>
</elementSpec>
All the parameters available for a given behaviour are defined as a part of the definition of the behaviour itself, as further discussed in section 22.5.5.8 Defining a processing model below.
<model predicate="sic and corr"
behaviour="alternate">
<param name="default" value="corr"/>
<param name="alternate" value="sic"/>
</model>
</elementSpec>
<model predicate="sic and corr"
behaviour="alternate">
<param name="default"
value="corr[@cert='high']"/>
<param name="alternate" value="sic"/>
</model>
</elementSpec>
<modelGrp output="web">
<model predicate="sic and corr"
behaviour="alternate">
<param name="default"
value="corr[@cert='high']"/>
<param name="alternate" value="sic"/>
</model>
<model predicate="abbr and expan"
behaviour="alternate">
<param name="default" value="expan[1]"/>
<param name="alternate" value="abbr"/>
</model>
<model predicate="orig and reg"
behaviour="alternate">
<param name="default" value="reg"/>
<param name="alternate" value="orig"/>
</model>
</modelGrp>
</elementSpec>
If nothing matches the XPath defining the value of a particular parameter (e.g. if in the above example there is no correction with cert=high) then the default parameter has no value. It is left to implementors to determine how null-valued parameters should be processed.
TEI: Outputs¶22.5.5.6 Outputs
As noted above, the output attribute is used to associate particular processing models with a specific type of output. The following example documents a range of processing intentions for the date element, intended to cope with at least the following three situations:
- there is text inside the element, and the output is print;
- there is no text inside the element but there is a when attribute, and the output is print;
- there is a when attribute, there is text inside the element, and the output is web
<modelGrp output="print">
<model predicate="text()"
behaviour="inline"/>
<model predicate="@when and not(text())"
behaviour="inline">
<param name="content" value="@when"/>
</model>
</modelGrp>
<model output="web" predicate="@when"
behaviour="alternate">
<param name="default" value="."/>
<param name="alternate" value="@when"/>
</model>
</elementSpec>
For output to print we supply two processing models, one for the simplest case where the content of the date is to be treated as an inline element, and the other for the case where there is no content and the value of the when attribute is to be used in its place. This is specified by a parameter, called content in this example. For output to web, we use the alternate behaviour discussed in the previous section to indicate that by default the content of the element will be used, while retaining access to the value of the when attribute, this time via a parameter called alternate.
TEI: Model sequence¶22.5.5.7 Model sequence
<modelSequence output="print">
<model behaviour="inline">
<param name="content" value="@n"/>
</model>
<model behaviour="footnote">
<param name="place" value="'foot'"/>
</model>
</modelSequence>
</elementSpec>
The value of the parameter called place above is an XPath expression supplying an arbitrary string (‘foot’), which is therefore quoted. It is left to implementors to validate or constrain the possible values for such expressions.
TEI: Defining a processing model¶22.5.5.8 Defining a processing model
<desc>create a hyperlink</desc>
<paramList>
<paramSpec ident="content">
<desc>supplies the location of some content describing the link</desc>
</paramSpec>
<paramSpec ident="uri">
<desc>supplies the location of the intended hyperlink</desc>
</paramSpec>
</paramList>
</valItem>
<desc versionDate="2015-08-21"
xml:lang="en">support display of alternative visualisations, for
example by displaying the preferred content, by displaying both in parallel, or by toggling
between the two.</desc>
<paramList>
<paramSpec ident="default">
<desc versionDate="2015-08-21"
xml:lang="en">supplies the location of the preferred
content</desc>
</paramSpec>
<paramSpec ident="alternate">
<desc versionDate="2015-08-21"
xml:lang="en">supplies the location of the alternative
content</desc>
</paramSpec>
</paramList>
</valItem>
The suggested behaviours provided by the model element are informally defined using commonly understood terminology, but specific details of how they should be implemented are left to the implementor. Such decisions may vary greatly depending on the kind of processing environment, the kind of output envisaged, etc. The intention is to reduce as far as possible any requirement for the implementor to be aware of TEI-specific rules, and to maximize the ability of the ODD to express processing intentions without fully specifying an implementation.
TEI: Implementation of Processing Models¶22.5.5.9 Implementation of Processing Models
- If a model element has no child param elements, the action specified by its behaviour should be applied to the whole element node concerned, including its child nodes of whatever type. If that behaviour requires distinguishing particular parts of the input, an implementation may choose either to make those distinctions itself, or to raise an error.
- If a model element has no predicate or output attribute then it is assumed to apply to all instances of the element defined in its parent elementSpec for all outputs. Otherwise its applicability depends on these attributes.
- Only one of the models is to be applied for a particular instance of the element, except when they appear within a modelSequence
- A ‘matching’ model is one where the element to be processed satisfies the XPath in the predicate attribute of the model or modelSequence and the current output method matches the method specified in the output attribute of the model, modelSequence, or a containing modelGrp. A model or modelSequence without a predicate always matches the element to be processed. A model, modelGrp, or modelSequence without an output attribute matches any output method.
- Processing Model implementations must execute only the first matching model or modelSequence in document order.
- If there are two or more model elements provided for an elementSpec but they have different output attributes then the implementation should choose the model appropriate to the desired output.
- If there are two or more model elements provided for an elementSpec but they have different predicate attributes then the implementation should choose the model whose predicate provides the most specific context (where specific is understood in the same way as in XSLT)
predicate="parent::list">
<desc versionDate="2015-03-02"
xml:lang="en">Model for list headings</desc>
<!-- ... -->
</model>
<model behaviour="heading">
<desc versionDate="2016-03-02"
xml:lang="en">Default model for all headings.</desc>
<!-- ... -->
</model>
TEI: Class Specifications¶22.6 Class Specifications
The element classSpec is used to document either an attribute class or a ‘model class’, as defined in section 1.3 The TEI Class System. A corresponding classRef element may be used to select a specific named class from those available.
- classSpec (class specification) contains reference information for a TEI element class; that is a group of elements which appear together in content models, or which share some common attribute, or both.
type indicates whether this is a model class or an attribute class - classRef points to the specification for an attribute or model class which is to be included in a schema
expand indicates how references to this class within a content model should be interpreted. - attList contains documentation for all the attributes associated with this element, as a series of attDef elements.
org (organization) specifies whether all the attributes in the list are available (org="group") or only one of them (org="choice")
<memberOf key="model.hiLike"/>
</classes>
ident="model.hiLike">
<desc>groups phrase-level elements related to highlighting that have no specific semantics </desc>
<classes>
<memberOf key="model.highlighted"/>
</classes>
</classSpec>
The function of a model class declaration is to provide another way of referring to a group of elements. It does not confer any other properties on the elements which constitute its membership.
The attribute type is used to distinguish between ‘model’ and ‘attribute’ classes. In the case of attribute classes, the attributes provided by membership in the class are documented by an attList element contained within the classSpec. In the case of model classes, no further information is needed to define the class beyond its description, its identifier, and optionally any classes of which it is a member.
When a model class is referenced in the content model of an element (i.e. by means of a classRef element within the content of an elementSpec), its meaning will depend on the value of its expand attribute.
<classRef key="model.hiLike"/>
</content>
<alternate>
<elementRef key="hi"/>
<elementRef key="it"/>
<elementRef key="bo"/>
</alternate>
</content>
(hi|it|bo)*
). However, a content model of <classRef expand="sequence"/>
would be equivalent to the following explicit content model: <sequence>
<elementRef key="hi"/>
<elementRef key="it"/>
<elementRef key="bo"/>
</sequence>
</content>
(hi,it,bo)*
).An attribute class (a classSpec of type atts) contains an attList element which lists the attributes that all the members of that class inherit from it. For example, the class att.interpLike defines a small set of attributes common to all elements which are members of that class: those attributes are listed by the attList element contained by the classSpec for att.interpLike. When processing the documentation elements for elements which are members of that class, an ODD processor is required to extend the attList (or equivalent) for such elements to include any attributes defined by the classSpec elements concerned. There is a single global attribute class, att.global, to which some modules contribute additional attributes when they are included in a schema.
TEI: Macro Specifications¶22.7 Macro Specifications
The macroSpec element is used to declare and document predefined strings or patterns not otherwise documented by the elements described in this section. A corresponding macroRef element may be used to select a specific named pattern from those available. Patterns are used as a shorthand chiefly to describe common content models and datatypes, but may be used for any purpose. The following elements are used to represent patterns:
- macroSpec (macro specification) documents the function and implementation of a pattern.
type indicates which type of entity should be generated, when an ODD processor is generating a module using XML DTD syntax. - macroRef points to the specification for some pattern which is to be included in a schema
key the identifier used for the required pattern within the source indicated.
TEI: Building a TEI Schema¶22.8 Building a TEI Schema
The specification elements, and some of their children, are all members of the att.identified class, from which they inherit the following attributes:
- att.identified provides the identifying attribute for elements which can be subsequently referenced by means of a key attribute.
ident supplies the identifier by which this element may be referenced. predeclare says whether this object should be predeclared in the tei infrastructure module. module supplies a name for the module in which this object is to be declared.
This attribute class is a subclass of the att.combinable class from which it (and some other elements) inherits the following attribute:
- att.combinable provides attributes indicating how multiple references to the same object in a schema should be combined
mode specifies the effect of this declaration on its parent object.
This attribute class, in turn, is a subclass of the att.deprecated class, from which it inherits the following attribute:
- att.deprecated provides attributes indicating how a deprecated feature will be treated in future releases.
validUntil provides a date before which the construct being defined will not be removed.
The validUntil attribute may be used to signal an intent to remove a construct from future versions of the schema being specified.
The elementSpec, attDef and schemaSpec specification elements also have an attribute which determines which namespace to which the object being created will belong. In the case of schemaSpec, this namespace is inherited by all the elements created in the schema, unless they have their own ns.
- att.namespaceable provides an attribute indicating the target namespace for an object being created
These attributes are used by an ODD processor to determine how declarations are to be combined to form a schema or DTD, as further discussed in this section.
TEI: TEI customizations¶22.8.1 TEI customizations
As noted above, a TEI schema is defined by a schemaSpec element containing an arbitrary mixture of explicit declarations for objects (i.e. elements, classes, patterns, or macro specifications) and references to other objects containing such declarations (i.e. references to specification groups, or to modules). A major purpose of this mechanism is to simplify the process of defining user customizations, by providing a formal method for the user to combine new declarations with existing ones, or to modify particular parts of existing declarations.
<moduleRef key="core"/>
<moduleRef key="linking"/>
</schemaSpec>
The value specified for the source attribute, when it is supplied as a URL, specifies any convenient location from which the relevant ODD files may be obtained. For the current release of the TEI Guidelines, a URL in the form http://www.tei-c.org/Vault/P5/x.y.z/xml/tei/odd/p5subset.xml
may be used, where x.y.z
represents the P5 version number, e.g. 1.3.0
. Alternatively, if the ODD files are locally installed, it may be more convenient to supply a value such as ../ODDs/p5subset.xml".
The value for the source attribute may be any form of URI. A set of TEI-conformant specifications in a form directly usable by an ODD processor must be available at the location indicated. When no source value is supplied, an ODD processor may either raise an error or assume that the location of the current release of the TEI Guidelines is intended.
If the source is specified in the form of a private URI, the form recommended is aaa:x.y.z
, where aaa
is a prefix indicating the markup language in use, and x.y.z
indicates the version number. For example, tei:1.2.1
should be used to reference release 1.2.1 of the current TEI Guidelines. When such a URI is used, it will usually be necessary to translate it before such a file can be used in blind interchange.
<moduleRef key="core"
except="add del orig reg"/>
<moduleRef key="linking"
include="linkGroup link"/>
</schemaSpec>
<moduleRef key="core"
except="add del orig reg"/>
<elementRef key="linkGroup"/>
<elementRef key="link"/>
</schemaSpec>
<moduleRef key="tei"/>
<!-- ... -->
<classRef key="att.global.linking"
include="corresp"/>
<!-- ... -->
</schemaSpec>
<moduleRef key="tei"/>
<!-- ... -->
<classRef key="att.global.linking"
except="copyOf exclude next prev sameAs select synch"/>
<!-- ... -->
</schemaSpec>
<moduleRef key="header"/>
<moduleRef key="verse"/>
<elementSpec ident="soundClip">
<classes>
<memberOf key="model.pPart.data"/>
</classes>
</elementSpec>
</schemaSpec>
<moduleRef key="header"/>
<moduleRef key="verse"/>
<elementSpec ident="soundClip">
<classes>
<memberOf key="model.pPart.data"/>
</classes>
<attList>
<attRef class="att.global.source"
name="source"/>
</attList>
</elementSpec>
</schemaSpec>
<moduleRef key="header"/>
<moduleRef key="teistructure"/>
<elementSpec ident="head" mode="change">
<content>
<macroRef key="macro.xtext"/>
</content>
</elementSpec>
</schemaSpec>
mode="change"
has the effect of over-riding only those children elements of the elementSpec which appear both in the original specification and in the new specification supplied above: content in this example. Note that if the value for mode were replace, the effect would be to replace all children elements of the original specification with the the children elements of the new specification, and thus (in this example) to delete all of them except content.A schema may not contain more than two declarations for any given component. The value of the mode attribute is used to determine exactly how the second declaration (and its constituents) should be combined with the first. The following table summarizes how a processor should resolve duplicate declarations; the term identifiable refers to those elements which can have a mode attribute:
mode value | existing declaration | effect |
add | no | add new declaration to schema; process its children in add mode |
add | yes | raise error |
replace | no | raise error |
replace | yes | retain existing declaration; process new children in replace mode; ignore existing children |
change | no | raise error |
change | yes | process identifiable children according to their modes; process unidentifiable children in replace mode; retain existing children where no replacement or change is provided |
delete | no | raise error |
delete | yes | ignore existing declaration and its children |
TEI: Combining TEI and Non-TEI Modules¶22.8.2 Combining TEI and Non-TEI Modules
start="TEI svg">
<moduleRef key="header"/>
<moduleRef key="core"/>
<moduleRef key="tei"/>
<moduleRef key="textstructure"/>
<moduleRef url="svg11.rng"/>
</schemaSpec>
<content>
<rng:define name="TEI_model.graphicLike"
combine="choice">
<rng:ref name="svg"/>
</rng:define>
</content>
</moduleRef>
This states that when the declarations from the svg11.rng module are combined with those from the other modules, the declaration for the model class model.graphicLike in the TEI module should be extended to include the element <svg:svg> as an alternative. This has the effect that elements in the TEI scheme which define their content model in terms of that element class (notably figure) can now include it. A RELAX NG schema generated from such a specification can be used to validate documents in which the TEI figure element contains any valid SVG representation of a graphic, embedded within an <svg:svg> element.
TEI: Linking Schemas to XML Documents¶22.8.3 Linking Schemas to XML Documents
Schemas can be linked to XML documents by means of the <?xml-model?> processing instruction described in the W3C Working Group Note Associating Schemas with XML documents (http://www.w3.org/TR/xml-model/). <?xml-model?> can be used for any type of schema, and may be used for multiple schemas:
<?xml-model href="tei_tite.rng" type="application/xml" ?> <?xml-model href="checkLinks.sch" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron" ?> <?xml-model href="tei_tite.odd" type="application/tei+xml" schematypens="http://www.tei-c.org/ns/1.0" ?>
This example includes a standard RELAX NG schema, a Schematron schema which might be used for checking that all pointing attributes point at existing targets, and also a link to the TEI ODD file from which the RELAX NG schema was generated. See also 2.3.9 The Schema Specification for details of another method of linking an ODD specification into your file by including a schemaSpec element in encodingDesc.
TEI: Module for Documentation Elements¶22.9 Module for Documentation Elements
The module described in this chapter makes available the following components:
- Module tagdocs: Documentation of TEI modules
- Elements defined: altIdent alternate anyElement att attDef attList attRef classRef classSpec classes code constraint constraintSpec content dataFacet dataRef dataSpec datatype defaultVal eg egXML elementRef elementSpec equiv exemplum gi ident listRef macroRef macroSpec memberOf model modelGrp modelSequence moduleRef moduleSpec outputRendition param paramList paramSpec remarks schemaSpec sequence specDesc specGrp specGrpRef specList tag textNode val valDesc valItem valList
- Classes defined: att.combinable att.deprecated att.identified att.namespaceable att.repeatable model.contentPart
- Macros defined: macro.schemaPattern
The selection and combination of modules to form a TEI schema is described in 1.2 Defining a TEI Schema.
The elements described in this chapter are all members of one of three classes: model.oddDecl, model.oddRef, or model.phrase.xml, with the exceptions of schemaSpec (a member of model.divPart) and both eg and egXML (members of model.common and model.egLike). All of these classes are declared along with the other general TEI classes, in the basic structure module documented in 1 The TEI Infrastructure.
In addition, some elements are members of the att.identified class, which is documented in 22.8.1 TEI customizations above, and make use of the macro.schemaPattern
pattern, which is documented in 22.5 Element Specifications above.