https://github.com/TEIC/TEI
Tip revision: 347c64fac3fa1a64ade0d8d1842813d4b8f7acec authored by Hugh Cayless on 12 May 2017, 16:57:59 UTC
Updates.
Updates.
Tip revision: 347c64f
USE.html
<!DOCTYPE html
SYSTEM "about:legacy-compat">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8" /><!--THIS FILE IS GENERATED FROM AN XML MASTER. DO NOT EDIT (4)--><title>23 Using the TEI - The TEI Guidelines</title><meta property="Language" content="en" /><meta property="DC.Title" content="23 Using the TEI - The TEI Guidelines" /><meta property="DC.Language" content="SCHEME=iso639 en" /><meta property="DC.Creator.Address" content="tei@oucs.ox.ac.uk" /><meta charset="utf-8" /><link href="guidelines.css" rel="stylesheet" type="text/css" /><link href="odd.css" rel="stylesheet" type="text/css" /><link rel="stylesheet" media="print" type="text/css" href="guidelines-print.css" /><script type="text/javascript" src="jquery-1.2.6.min.js"></script><script type="text/javascript" src="columnlist.js"></script><script type="text/javascript" src="popupFootnotes.js"></script><script type="text/javascript">
$(function() {
$('ul.attrefs-class').columnizeList({cols:3,width:30,unit:'%'});
$('ul.attrefs-element').columnizeList({cols:3,width:30,unit:'%'});
$(".displayRelaxButton").click(function() {
$(this).parent().find('.RNG_XML').toggle();
$(this).parent().find('.RNG_Compact').toggle();
});
$(".tocTree .showhide").click(function() {
$(this).find(".tocShow,.tocHide").toggle();
$(this).parent().find("ul.continuedtoc").toggle();
});
})
</script><script type="text/javascript"><!--
var displayXML=0;
states=new Array()
states[0]="element-a"
states[1]="element-b"
states[2]="element-c"
states[3]="element-d"
states[4]="element-e"
states[5]="element-f"
states[6]="element-g"
states[7]="element-h"
states[8]="element-i"
states[9]="element-j"
states[10]="element-k"
states[11]="element-l"
states[12]="element-m"
states[13]="element-n"
states[14]="element-o"
states[15]="element-p"
states[16]="element-q"
states[17]="element-r"
states[18]="element-s"
states[19]="element-t"
states[20]="element-u"
states[21]="element-v"
states[22]="element-w"
states[23]="element-x"
states[24]="element-y"
states[25]="element-z"
function startUp() {
}
function hideallExcept(elm) {
for (var i = 0; i < states.length; i++) {
var layer;
if (layer = document.getElementById(states[i]) ) {
if (states[i] != elm) {
layer.style.display = "none";
}
else {
layer.style.display = "block";
}
}
}
var mod;
if ( mod = document.getElementById('byMod') ) {
mod.style.display = "none";
}
}
function showall() {
for (var i = 0; i < states.length; i++) {
var layer;
if (layer = document.getElementById(states[i]) ) {
layer.style.display = "block";
}
}
}
function showByMod() {
hideallExcept('');
var mod;
if (mod = document.getElementById('byMod') ) {
mod.style.display = "block";
}
}
--></script></head><body><div id="container"><div id="banner"><img src="Images/banner.jpg" alt="Text Encoding Initiative logo and banner" /></div></div><div class="mainhead"><h1>P5:
Guidelines for Electronic Text Encoding and Interchange</h1><p>Version 3.1.1a. Last updated on
10th May 2017, revision bd8dda3</p></div><div id="onecol" class="main-content"><h2><span class="headingNumber">23 </span>Using the TEI</h2><div class="div1" id="USE"><div class="miniTOC miniTOC_left"><p><span class="subtochead">Table of contents</span></p><div class="subtoc"><ul class="subtoc"><li class="subtoc"><a class="subtoc" href="USE.html#MEDIATYPE" title="Serving TEI files with the TEI Media Type">23.1 Serving TEI files with the TEI Media Type</a></li><li class="subtoc"><a class="subtoc" href="USE.html#DT" title="36">23.2 Obtaining the TEI</a></li><li class="subtoc"><a class="subtoc" href="USE.html#MD" title="Customization">23.3 Customization</a></li><li class="subtoc"><a class="subtoc" href="USE.html#CF" title="Conformance">23.4 Conformance</a></li><li class="subtoc"><a class="subtoc" href="USE.html#IM" title="Implementation of an ODD System">23.5 Implementation of an ODD System</a></li></ul></div><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="TD.html"><span class="headingNumber">22 </span>Documentation Elements</a></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="REF-CLASSES-MODEL.html"><span class="headingNumber">Appendix A </span>Model Classes</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><p>This section discusses some technical topics concerning the deployment of the TEI markup scheme documented elsewhere in these Guidelines. In section <a class="link_ptr" href="USE.html#MD" title="Customization"><span class="headingNumber">23.3 </span>Customization</a> we discuss the scope and variety of the TEI customization mechanisms. In <a class="link_ptr" href="USE.html#CF" title="Conformance"><span class="headingNumber">23.4 </span>Conformance</a> we define the notions of <span class="term">TEI Conformance</span> and <span class="term">TEI Extension</span>. Since the ODD markup description language defined in chapter <a class="link_ptr" href="TD.html" title="27"><span class="headingNumber">22 </span>Documentation Elements</a> is fundamental to the way conformance and customization are handled in the TEI system, these two definitional sections are followed by a section (<a class="link_ptr" href="USE.html#IM" title="Implementation of an ODD System"><span class="headingNumber">23.5 </span>Implementation of an ODD System</a>) which describes the intended behaviour of an ODD processor.</p><div class="div2" id="MEDIATYPE"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#DT"><span class="headingNumber">23.2 </span>Obtaining the TEI</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h3><span class="bookmarklink"><a class="bookmarklink" href="#MEDIATYPE" title="link to this section "><span class="invisible">TEI: Serving TEI files with the TEI Media Type</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.1 </span><span class="head">Serving TEI files with the TEI Media Type</span></h3><p>In February 2011, the media type <code>application/tei+xml</code> was registered with IANA for <span class="q">‘markup languages defined in accordance with the Text Encoding and Interchange guidelines’</span> (<a class="link_ref" href="https://www.rfc-editor.org/info/rfc6129">RFC 6129</a>). We recommend that any XML file whose root element is in the TEI namespace be served with the media type <code>application/tei+xml</code> to enable and encourage automated recognition and processing of TEI files by external applications.</p></div><div class="div2" id="DT"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#MEDIATYPE"><span class="headingNumber">23.1 </span>Serving TEI files with the TEI Media Type</a></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#MD"><span class="headingNumber">23.3 </span>Customization</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h3><span class="bookmarklink"><a class="bookmarklink" href="#DT" title="link to this section "><span class="invisible">TEI: Obtaining the TEI</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.2 </span><span class="head">Obtaining the TEI</span></h3><p>As discussed in chapter <a class="link_ptr" href="TD.html" title="27"><span class="headingNumber">22 </span>Documentation Elements</a>, all components of the TEI scheme are generated from a single set of TEI XML source files. Schemas can be generated in each of XML DTD language, W3C schema language, and RELAX NG schema language. Documentation can be generated in a variety of commonly-used document formats, including HTML, DOCX, or PDF. </p><p>TEI components are freely available over the Internet and elsewhere. The canonical home for the TEI source, the schema fragments generated from it, and example modifications, is the TEI repository at <a class="link_ptr" href="https://github.com/TEIC/TEI"><span>https://github.com/TEIC/TEI</span></a>; versions are also available in other formats, along with copies of these Guidelines and related materials, from the TEI web site at <a class="link_ptr" href="http://www.tei-c.org/"><span>http://www.tei-c.org/</span></a>.</p></div><div class="div2" id="MD"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#DT"><span class="headingNumber">23.2 </span>Obtaining the TEI</a></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#CF"><span class="headingNumber">23.4 </span>Conformance</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h3><span class="bookmarklink"><a class="bookmarklink" href="#MD" title="link to this section "><span class="invisible">TEI: Customization</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.3 </span><span class="head">Customization</span></h3><p>These Guidelines provide an encoding scheme suitable for encoding a very wide range of texts, and capable of supporting a wide variety of applications. For this reason, the TEI scheme supports a variety of different approaches to solving similar problems, and also defines a much richer set of elements than is likely to be necessary in any given project. Furthermore, the TEI scheme may be extended in well-defined and documented ways for texts that cannot be conveniently or appropriately encoded using what is provided. For these reasons, it is almost impossible to use the TEI scheme without customizing it in some way. </p><p>This section describes how the TEI encoding scheme may be customized, and should be read in conjunction with chapter <a class="link_ptr" href="TD.html" title="27"><span class="headingNumber">22 </span>Documentation Elements</a>, which describes how a specific application of the TEI encoding scheme should be documented. The documentation system described in that chapter is, like the rest of the TEI scheme, independent of any particular schema or document type definition language.</p><p>Formally speaking, these Guidelines provide both syntactic rules about how elements and attributes may be used in valid documents and semantic recommendations about what interpretation should be attached to a given syntactic construct. In this sense, they provide both a <span class="term">document type definition</span> and a <span class="term">document type declaration</span>. More exactly, we may distinguish between the <span class="term">TEI Abstract Model</span>, which defines a set of related concepts, and the <span class="term">TEI schema</span> which defines a set of syntactic rules and constraints. Many (though not all) of the semantic recommendations are provided solely as informal descriptive prose, though some of them are also enforced by means of such constructs as datatypes (see <a class="link_ptr" href="ST.html#DTYPES" title="Datatype Specifications"><span class="headingNumber">1.4.2 </span>Datatype Specifications</a>), or by schema constraints expressed using the Schematron language. Although the descriptions have been written with care, there will inevitably be cases where the intention of the contributors has not been conveyed with sufficient clarity to prevent users of these Guidelines from ‘extending’ them in the sense of attaching slightly variant semantics to them.</p><p>Beyond this unintentional semantic extension, some of the elements described can intentionally be used in a variety of ways; for example, the element <a class="gi" title="contains a note or annotation." href="ref-note.html">note</a> has an attribute <span class="att">type</span> which can take on arbitrary string values, depending on how it is used in a document. A new type of <span class="q">‘note’</span>, therefore, requires no change in the existing model. On the other hand, for many applications, it may be desirable to constrain the possible values for the <span class="att">type</span> attribute to a small set of possibilities. A schema modified in this way would no longer necessarily regard as valid the same set of documents as the corresponding unmodified TEI schema, but would remain faithful to the same conceptual model.</p><p>This section explains how the TEI scheme can be customized by suppressing elements, modifying classes of elements, adding elements, and renaming elements. Documents which validate against an application of the TEI scheme which has been customized in this way may or may not be considered ‘TEI-conformant’, as further discussed in section <a class="link_ptr" href="USE.html#CF" title="Conformance"><span class="headingNumber">23.4 </span>Conformance</a>.</p><p>The TEI scheme is designed to support modification and customization in a documented way that can be validated by an XML processor. This is achieved by writing a small TEI-conformant document, from which an appropriate processor can generate both human-readable documentation, and a schema expressed in a language such as RELAX NG or DTD. The mechanisms used to instantiate a TEI schema differ for different schema languages, and are therefore not defined here. In XML DTDs, for example, extensive use is made of parameter entities, while in RELAX NG schemas, extensive use is made of patterns. In either case, the names of elements and, wherever possible, their attributes and content models are defined indirectly. The syntax used to implement this indirection also varies with the schema language used, but the underlying constructs in the TEI Abstract Model are given the same names. </p><p>As further discussed in section <a class="link_ptr" href="ST.html" title="3"><span class="headingNumber">1 </span>The TEI Infrastructure</a>, the TEI encoding scheme comprises a set of class and macro declarations, and a number of <span class="term">modules</span>. Each module is made up of element and attribute declarations, and a schema is made by combining a particular set of modules together. In the absence of any other kind of customization, when modules are combined together: </p><ol class="numbered"><li class="item">all the elements defined by the module (and described in the corresponding section of these Guidelines) are included in the schema;</li><li class="item">each such element is identified by the canonical name given it in these Guidelines;</li><li class="item">the content model of each such element is as defined by these Guidelines;</li><li class="item">the names, datatypes, and permitted values declared for each attribute associated with each such element are as given in these Guidelines;</li><li class="item">the elements comprising element classes and the meaning of macro declarations expressed in terms of element classes is determined by the particular combination of modules selected.</li></ol><p> The TEI customization mechanisms allow the user to control this behaviour as follows: </p><ol class="numbered"><li class="item">particular elements may be suppressed, removing them from any classes in which they are members, and also from any generated schema; </li><li class="item">within certain limits, the name (generic identifier) associated with an element may be changed, without changing the semantic or syntactic properties of the element;</li><li class="item">new elements may be added to an existing class, thus making them available in macros or content models defined in terms of those classes;</li><li class="item">additional attributes, or attribute values, may be specified for an individual element or for classes of elements; </li><li class="item">within certain limits, attributes, or attribute values, may also be removed either from an individual element or for classes of elements; </li><li class="item">the characteristics inherited by one class from another class may be modified by modifying its class membership: all members of the class then inherit the changed characteristics;</li><li class="item">the set of values legal for an attribute or attribute class may be constrained or relaxed by supplying or modifying a value list, or by modifying its datatype.</li></ol><p> The modification mechanisms presented in this section are quite general, and may be used to make all the types of changes just listed.</p><p>The recommended way of implementing and documenting all such modifications is by means of the ODD system described in chapter <a class="link_ptr" href="TD.html" title="27"><span class="headingNumber">22 </span>Documentation Elements</a>; in the remainder of this section we give specific examples to illustrate how that system may be applied. An ODD processor, such as the Roma application supported by the TEI, or any other comparable set of stylesheets will use the declarations provided by an ODD to generate appropriate sets of declarations in a specific schema language such as RELAX NG or the XML DTD language. We do not discuss in detail here how this should be done, since the details are schema language-specific; some background information about the methods used for XML DTD and RELAX NG schema generation is however provided in section <a class="link_ptr" href="ST.html#STIN" title="Defining a TEI Schema"><span class="headingNumber">1.2 </span>Defining a TEI Schema</a>. Several example ODD files are also provided as part of the standard TEI release: see further section <a class="link_ptr" href="USE.html#MDlite" title="Examples of Modification"><span class="headingNumber">23.3.4 </span>Examples of Modification </a> below.</p><div class="div3" id="MDMD"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#MDNS"><span class="headingNumber">23.3.2 </span>Modification and Namespaces</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h4><span class="bookmarklink"><a class="bookmarklink" href="#MDMD" title="link to this section "><span class="invisible">TEI: Kinds of Modification</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.3.1 </span><span class="head">Kinds of Modification</span></h4><p>For ease of discussion, we distinguish the following different kinds of modification: </p><ol class="numbered"><li class="item">deletion of elements;</li><li class="item">renaming of elements;</li><li class="item">modification of content models;</li><li class="item">modification of attribute and attribute-value lists;</li><li class="item">modification of class membership;</li><li class="item">addition of new elements.</li></ol><p> Each of these is described in the following sections.</p><p>Each kind of modification changes the set of documents that will be considered valid according to the resulting schema. A schema derived from any combination of unmodified TEI declarations (an "unmodified schema") may be thought of as defining a certain set of documents. A schema deriving from a combination of modified TEI declarations (a "modified schema") will define a different set of documents. The set of documents valid according to the modified schema may or may not be properly contained by the set of documents considered to be valid according to the unmodified schema. We use the term <span class="term">clean modification</span> for the former case, where the set of documents defined by the modified schema is a proper subset of the set of documents defined by the unmodified schema. Where this is not the case, that is, where the modified schema considers valid some documents which the unmodified schema does not, we use the term <span class="term">unclean modification</span>. Despite this terminology, unclean modifications are not particularly deprecated, and their use may often be vital to the success of a project. The concept is introduced solely to distinguish the effects of different kinds of modification.</p><div class="div4" id="MDMDSU"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#MDMDNM"><span class="headingNumber">23.3.1.2 </span>Renaming of Elements</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h5><span class="bookmarklink"><a class="bookmarklink" href="#MDMDSU" title="link to this section "><span class="invisible">TEI: Deletion of Elements</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.3.1.1 </span><span class="head">Deletion of Elements</span></h5><p>The simplest way to modify the supplied modules is to suppress one or more of the supplied elements. This is simply done by setting the <span class="att">mode</span> attribute to <span class="val">delete</span> on an <a class="gi" title="(element specification) documents the structure, content, and purpose of a single element type." href="ref-elementSpec.html">elementSpec</a> for the element concerned.</p><div class="p">For example, if the <a class="gi" title="contains a note or annotation." href="ref-note.html">note</a> element is not to be used in a particular application, the schema specification concerned will contain a declaration like the following: <div id="index-egXML-d52e150379" class="pre egXML_valid"><span class="element"><elementSpec <span class="attribute">ident</span>="<span class="attributevalue">note</span>" <span class="attribute">module</span>="<span class="attributevalue">core</span>"<br /> <span class="attribute">mode</span>="<span class="attributevalue">delete</span>"/></span></div> The <span class="att">ident</span> attribute here supplies the canonical name of the element to be deleted, the <span class="att">module</span> attribute identifies the module in which this element is declared, and the <span class="att">mode</span> attribute specifies what is to be done with it. Note that the module name must be supplied explicitly, and that the schema specification in which this declaration appears must also contain a reference to the module itself. The full specification for a schema in which this modification is applied would thus be something like the following: <div id="index-egXML-d52e150392" class="pre egXML_valid"><span class="element"><schemaSpec <span class="attribute">ident</span>="<span class="attributevalue">mySchema</span>"></span><br /> <span class="element"><moduleRef <span class="attribute">key</span>="<span class="attributevalue">core</span>"/></span><br /><span class="comment"><!-- other modules used by this schema --></span><br /> <span class="element"><elementSpec <span class="attribute">ident</span>="<span class="attributevalue">note</span>" <span class="attribute">module</span>="<span class="attributevalue">core</span>"<br /> <span class="attribute">mode</span>="<span class="attributevalue">delete</span>"/></span><br /><span class="element"></schemaSpec></span></div></div><p>In most cases, deletion is a clean modification, since most elements are optional. Documents that are valid with respect to the modified schema are also valid according to the unmodified schema. To say this another way, the set of documents matching the new schema is contained by the set of documents matching the original schema.</p><p>There are however some elements in the TEI scheme which have mandatory children; for example, the element <a class="gi" title="(list of persons) contains a list of descriptions, each of which provides information about an identifiable person or a group of people, for example the participants in a language interaction, or the people referred to in a historical source." href="ref-listPerson.html">listPerson</a> must contain at least one element from the <span class="ident">model.personLike</span> class. If that class has no members because all of its member elements have been removed, then the content model cannot be satisfied. A modification which keeps <a class="gi" title="(list of persons) contains a list of descriptions, each of which provides information about an identifiable person or a group of people, for example the participants in a language interaction, or the people referred to in a historical source." href="ref-listPerson.html">listPerson</a> but removes all of its possible children would therefore be regarded as unclean. So long as at least one member of the class remains available, however, deleting other members would not have this effect, and would therefore be regarded as a clean modification.</p><p>In general, whenever the element deleted by a modification is mandatory within the content model of some other (undeleted) element, the result is an unclean modification, and may also break the TEI Abstract Model (<a class="link_ptr" href="USE.html#CFAM" title="Conformance to the TEI Abstract Model"><span class="headingNumber">23.4.3 </span>Conformance to the TEI Abstract Model</a>). However, the parent of a mandatory child can be safely removed if it is itself optional.</p><p>To determine whether or not an element is mandatory in a given context, the user must inspect the content model of the element concerned. In most cases, content models are expressed in terms of model classes rather than elements; hence, removing an element will generally be a clean modification, since there will generally be other members of the class available. If a class is completely depopulated by a modification, then the cleanliness of the modification will depend upon whether or not the class reference is mandatory or optional, in the same way as for an individual element.</p></div><div class="div4" id="MDMDNM"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#MDMDSU"><span class="headingNumber">23.3.1.1 </span>Deletion of Elements</a></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#MDMDCM"><span class="headingNumber">23.3.1.3 </span>Modification of Content Models</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h5><span class="bookmarklink"><a class="bookmarklink" href="#MDMDNM" title="link to this section "><span class="invisible">TEI: Renaming of Elements</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.3.1.2 </span><span class="head">Renaming of Elements</span></h5><p>Every element and other named markup construct in the TEI scheme has a <span class="term">canonical name</span>, usually in the English language: this name is supplied as the value of the <span class="att">ident</span> attribute on the <a class="gi" title="(element specification) documents the structure, content, and purpose of a single element type." href="ref-elementSpec.html">elementSpec</a>, <a class="gi" title="(attribute definition) contains the definition of a single attribute." href="ref-attDef.html">attDef</a>, <a class="gi" title="(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." href="ref-classSpec.html">classSpec</a>, or <a class="gi" title="(macro specification) documents the function and implementation of a pattern." href="ref-macroSpec.html">macroSpec</a> used to define it. The element or attribute declaration used within a schema generated from that specification may however be different, thus permitting schemas to be written using elements with generic identifiers from a different language, or otherwise modified. There may be many alternative identifiers for the same markup construct, and an ODD processor may choose which of them to use for a given purpose. Each such alternative name is supplied by means of an <a class="gi" title="(alternate identifier) supplies the recommended XML name for an element, class, attribute, etc. in some language." href="ref-altIdent.html">altIdent</a> element within the specification element concerned.</p><div class="p">For example, the following declaration converts <a class="gi" title="contains a note or annotation." href="ref-note.html">note</a> to <span class="gi"><annotation></span>: <div id="index-egXML-d52e150452" class="pre egXML_valid"><span class="element"><elementSpec <span class="attribute">ident</span>="<span class="attributevalue">note</span>" <span class="attribute">module</span>="<span class="attributevalue">core</span>"<br /> <span class="attribute">mode</span>="<span class="attributevalue">change</span>"></span><br /> <span class="element"><altIdent></span>annotation<span class="element"></altIdent></span><br /><span class="element"></elementSpec></span></div> Note that the <span class="att">mode</span> attribute on the <a class="gi" title="(element specification) documents the structure, content, and purpose of a single element type." href="ref-elementSpec.html">elementSpec</a> now takes the value <span class="val">change</span> to indicate that those parts of the element specification not supplied are to be inherited from the standard definition. The content of the <a class="gi" title="(alternate identifier) supplies the recommended XML name for an element, class, attribute, etc. in some language." href="ref-altIdent.html">altIdent</a> element will be used in place of the canonical <span class="att">ident</span> value in the schema generated.</div><p>Renaming in this way is always a <span class="term">reversible</span> modification. Although it is an inherently unclean modification (because the set of documents matched by the resulting schema is not contained by the set matched by its unmodified equivalent), the process of converting any document in which elements have been renamed into an exactly equivalent document using canonical names is completely deterministic, requiring only access to the ODD in which the renaming has been specified. This assumes that the renamed elements used are not placed in the TEI namespace but either use a null namespace or some user-defined namespace, as further discussed in <a class="link_ptr" href="USE.html#MDNS" title="Modification and Namespaces"><span class="headingNumber">23.3.2 </span>Modification and Namespaces</a>; if this is not the case, care must be taken to avoid name collision between the new name and all existing TEI names. Furthermore, unclean modifications which do not specify a namespace are not conformant (see further <a class="link_ptr" href="USE.html#MD" title="Customization"><span class="headingNumber">23.3 </span>Customization</a>)</p></div><div class="div4" id="MDMDCM"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#MDMDNM"><span class="headingNumber">23.3.1.2 </span>Renaming of Elements</a></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#MDMDAL"><span class="headingNumber">23.3.1.4 </span>Modification of Attribute and Attribute Value Lists</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h5><span class="bookmarklink"><a class="bookmarklink" href="#MDMDCM" title="link to this section "><span class="invisible">TEI: Modification of Content Models</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.3.1.3 </span><span class="head">Modification of Content Models</span></h5><div class="p">The content model for an element in the TEI scheme is defined by means of a <a class="gi" title="(content model) contains the text of a declaration for the schema documented." href="ref-content.html">content</a> element within the <a class="gi" title="(element specification) documents the structure, content, and purpose of a single element type." href="ref-elementSpec.html">elementSpec</a> which specifies it. For example, the specification for the element <a class="gi" title="contains a single-word, multi-word, or symbolic designation which is regarded as a technical term." href="ref-term.html">term</a> provided by these Guidelines contains a <a class="gi" title="(content model) contains the text of a declaration for the schema documented." href="ref-content.html">content</a> element like the following: <div id="index-egXML-d52e150500" class="pre egXML_valid"><span class="element"><content></span><br /> <span class="element"><macroRef <span class="attribute">key</span>="<span class="attributevalue">macro.phraseSeq</span>"/></span><br /><span class="element"></content></span></div> This indicates that the content model consists of a reference to a macro called <span class="ident-macro">macro.phraseSeq</span>. Further examination shows that this macro in turn expands to an optional repeatable alternation of text (<a class="gi" title="indicates the presence of a text node in a content model" href="ref-textNode.html">textNode</a>) with references to three other classes (<a class="link_odd" title="groups elements used to represent individual non-Unicode characters or glyphs." href="ref-model.gLike.html">model.gLike</a>, <a class="link_odd" title="groups elements which can occur at the level of individual words or phrases." href="ref-model.phrase.html">model.phrase</a>, or <a class="link_odd" title="groups elements which may appear at any point within a TEI text." href="ref-model.global.html">model.global</a>). For some particular application it might be preferable to insist that <a class="gi" title="contains a single-word, multi-word, or symbolic designation which is regarded as a technical term." href="ref-term.html">term</a> elements should only contain plain text, excluding these other possibilities.<span id="Note126_return"><a class="notelink" title="Excluding model.gLike is generally inadvisable however, since without it the resulting schema has no way of referencing non-Unicode characters." href="#Note126"><sup>89</sup></a></span> This could be achieved simply by supplying a specification for <a class="gi" title="contains a single-word, multi-word, or symbolic designation which is regarded as a technical term." href="ref-term.html">term</a> like the following: <div id="index-egXML-d52e150533" class="pre egXML_valid"><span class="element"><elementSpec <span class="attribute">ident</span>="<span class="attributevalue">term</span>" <span class="attribute">module</span>="<span class="attributevalue">core</span>"<br /> <span class="attribute">mode</span>="<span class="attributevalue">change</span>"></span><br /> <span class="element"><content></span><br /> <span class="element"><textNode/></span><br /> <span class="element"></content></span><br /><span class="element"></elementSpec></span></div></div><p>This is a clean modification which does not change the meaning of a TEI element; there is therefore no need to assign the element to some other namespace than that of the TEI, though it may be considered good practice; see further <a class="link_ptr" href="USE.html#MDNS" title="Modification and Namespaces"><span class="headingNumber">23.3.2 </span>Modification and Namespaces</a> below.</p><p>A change of this kind, which simplifies the possible content of an element by reducing its model to one of its existing components, is always clean, because the set of documents matched by the resulting schema is a subset of the set of documents which would have been matched by the unmodified schema.</p><p>Note that content models are generally defined (as far as possible) in terms of references to model classes, rather than to explicit elements. This means that the need to modify content models is greatly reduced: if an element is deleted or modified, for example, then the deletion or modification will be available for every content model which references that element via its class, as well as those which reference it explicitly. For this reason it is not (in general) good practice to replace class references by explicit element references, since this may have unintended side effects. </p><p>An unqualified reference to an element class within a content model generates a content model which is equivalent to an alternation of all the members of the class referenced. Thus, a content model which refers to the model class <a class="link_odd" title="groups elements which can occur at the level of individual words or phrases." href="ref-model.phrase.html">model.phrase</a> will generate a content model in which any one of the members of that class is equally acceptable. The <a class="gi" title="points to the specification for an attribute or model class which is to be included in a schema" href="ref-classRef.html">classRef</a> element used to reference a class has an <span class="att">expand</span> attribute which may be used to vary this behaviour, for example to require <span class="q">‘an optional repeatable alternation of all members of a class’</span>, <span class="q">‘a sequence containing no more than one of each member of the class’</span>, etc. as described further in <a class="link_ptr" href="TD.html#TDCLA" title="Class Specifications"><span class="headingNumber">22.6 </span>Class Specifications</a>.</p><p>Content model changes which are not simple restrictions on an existing model should be undertaken with caution. The set of documents matching the schema which results from such changes is unlikely to be contained by the set of documents matching the unmodified schema, and such changes are therefore regarded as unclean. When content models are changed or extended, care should be taken to respect the existing semantics of the element concerned as stated in these Guidelines. For example, the element <a class="gi" title="(verse line) contains a single, possibly incomplete, line of verse." href="ref-l.html">l</a> is defined as containing a line of verse. It would not therefore make sense to redefine its content model so that it could also include members of the class <a class="link_odd" title="groups paragraph-like elements." href="ref-model.pLike.html">model.pLike</a>: such a modification although syntactically feasible would not be regarded as TEI-conformant because it breaks the TEI Abstract Model.</p></div><div class="div4" id="MDMDAL"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#MDMDCM"><span class="headingNumber">23.3.1.3 </span>Modification of Content Models</a></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#MDMDCL"><span class="headingNumber">23.3.1.5 </span>Class Modification</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h5><span class="bookmarklink"><a class="bookmarklink" href="#MDMDAL" title="link to this section "><span class="invisible">TEI: Modification of Attribute and Attribute Value Lists</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.3.1.4 </span><span class="head">Modification of Attribute and Attribute Value Lists</span></h5><p>The attributes applicable to a given element may be specified in two ways: they may be given explicitly, by means of an <a class="gi" title="contains documentation for all the attributes associated with this element, as a series of <attDef> elements." href="ref-attList.html">attList</a> element within the corresponding <a class="gi" title="(element specification) documents the structure, content, and purpose of a single element type." href="ref-elementSpec.html">elementSpec</a>, or they may be inherited from an attribute class, as specified in the <a class="gi" title="specifies all the classes of which the documented element or class is a member or subclass." href="ref-classes.html">classes</a> element. To add a new attribute to an element, the schema builder should therefore first check to see whether this attribute is already available from some existing attribute class. If it is, then the simplest method of adding it will be to make the element in question a member of that class, as further discussed below. If this is not possible, then a new <a class="gi" title="(attribute definition) contains the definition of a single attribute." href="ref-attDef.html">attDef</a> element must be added to the existing <a class="gi" title="contains documentation for all the attributes associated with this element, as a series of <attDef> elements." href="ref-attList.html">attList</a> for the element in question.</p><p>Whichever method is adopted, the modification capabilities are the same as those available for elements. Attributes may be added or deleted from the list, using the <span class="att">mode</span> attribute on <a class="gi" title="(attribute definition) contains the definition of a single attribute." href="ref-attDef.html">attDef</a> in the same way as on <a class="gi" title="(element specification) documents the structure, content, and purpose of a single element type." href="ref-elementSpec.html">elementSpec</a>. The <span class="q">‘content’</span> of an attribute is defined by means of the <a class="gi" title="specifies the declared value for an attribute, by referring to any datatype defined by the chosen schema language." href="ref-datatype.html">datatype</a>, <a class="gi" title="(value list) contains one or more <valItem> elements defining possible values." href="ref-valList.html">valList</a>, or <a class="gi" title="(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." href="ref-valDesc.html">valDesc</a> elements within the <a class="gi" title="(attribute definition) contains the definition of a single attribute." href="ref-attDef.html">attDef</a> element. Any of these elements may be changed.</p><p>Suppose, for example, that we wish to add two attributes to the <a class="gi" title="(example) contains any kind of illustrative example." href="ref-eg.html">eg</a> element (used to indicate examples in a text), <span class="att">type</span> to characterize the example in some way, and <span class="att">valid</span> to indicate whether the example is considered valid or not. A quick glance through the Guidelines indicates that the attribute class <a class="link_odd" title="provides attributes which can be used to classify or subclassify elements in any way." href="ref-att.typed.html">att.typed</a> could be used to provide the <span class="att">type</span> attribute, but there is no comparable class which will provide a <span class="att">valid</span> attribute. The existing <a class="gi" title="(example) contains any kind of illustrative example." href="ref-eg.html">eg</a> element in fact has no local attributes defined for it at all: we will therefore need to add not only an <a class="gi" title="(attribute definition) contains the definition of a single attribute." href="ref-attDef.html">attDef</a> element to define the new attribute, but also an <a class="gi" title="contains documentation for all the attributes associated with this element, as a series of <attDef> elements." href="ref-attList.html">attList</a> to hold it.</p><div class="p">We begin by adding the new <span class="att">valid</span> attribute: <div id="index-egXML-d52e150656" class="pre egXML_valid"><span class="element"><elementSpec <span class="attribute">ident</span>="<span class="attributevalue">eg</span>" <span class="attribute">module</span>="<span class="attributevalue">tagdocs</span>"<br /> <span class="attribute">mode</span>="<span class="attributevalue">change</span>"></span><br /> <span class="element"><attList></span><br /> <span class="element"><attDef <span class="attribute">ident</span>="<span class="attributevalue">valid</span>" <span class="attribute">mode</span>="<span class="attributevalue">add</span>"<br /> <span class="attribute">ns</span>="<span class="attributevalue">http://www.example.com/ns/nonTEI</span>"></span><br /> <span class="element"><desc></span>indicates whether or not the example is considered to be valid<span class="element"></desc></span><br /> <span class="element"><datatype></span><br /> <span class="element"><dataRef <span class="attribute">key</span>="<span class="attributevalue">teidata.truthValue</span>"/></span><br /> <span class="element"></datatype></span><br /> <span class="element"></attDef></span><br /> <span class="element"></attList></span><br /><span class="element"></elementSpec></span></div></div><p>The value supplied for the <span class="att">mode</span> attribute on the <a class="gi" title="(attribute definition) contains the definition of a single attribute." href="ref-attDef.html">attDef</a> element is <span class="val">add</span>; if this attribute already existed on the element we are modifying this should generate an error, since a specification cannot have more than one attribute of the same name. If the attribute is already present, we can replace the whole of the existing declaration by supplying <span class="val">replace</span> as the value for <span class="att">mode</span>; alternatively, we can change some parts of an existing declaration only by supplying just the new parts, and setting <span class="val">change</span> as the value for <span class="att">mode</span>.</p><p>Because the new attribute is not defined by the TEI, we must specify a namespace for it on the <a class="gi" title="(attribute definition) contains the definition of a single attribute." href="ref-attDef.html">attDef</a>; see further <a class="link_ptr" href="USE.html#MDNS" title="Modification and Namespaces"><span class="headingNumber">23.3.2 </span>Modification and Namespaces</a>.</p><p>As noted above, adding the new <span class="att">type</span> attribute involves changing this element's class membership; we therefore discuss that in the next section (<a class="link_ptr" href="USE.html#MDMDCL" title="Class Modification"><span class="headingNumber">23.3.1.5 </span>Class Modification</a>).</p><p>The canonical name for the new attribute is <span class="att">valid</span>, and is supplied on the <span class="att">ident</span> attribute of the <a class="gi" title="(attribute definition) contains the definition of a single attribute." href="ref-attDef.html">attDef</a> element. In this simple example, we supply only a description and datatype for the new attribute; the former is given by the <a class="gi" title="(description) contains a brief description of the object documented by its parent element, typically a documentation element or an entity." href="ref-desc.html">desc</a> element, and the latter by the <a class="gi" title="specifies the declared value for an attribute, by referring to any datatype defined by the chosen schema language." href="ref-datatype.html">datatype</a> element. (There are of course many other pieces of information which could be supplied, as documented in <a class="link_ptr" href="TD.html" title="27"><span class="headingNumber">22 </span>Documentation Elements</a>). The content of the <a class="gi" title="specifies the declared value for an attribute, by referring to any datatype defined by the chosen schema language." href="ref-datatype.html">datatype</a> element is a <a class="gi" title="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" href="ref-dataRef.html">dataRef</a> element which references an existing TEI data specification.</p><div class="p">It is often desirable to constrain the possible values for an attribute to a greater extent than is possible by simply supplying a TEI datatype for it. This facility is provided by the <a class="gi" title="(value list) contains one or more <valItem> elements defining possible values." href="ref-valList.html">valList</a> element, which can also appear as a child of the <a class="gi" title="(attribute definition) contains the definition of a single attribute." href="ref-attDef.html">attDef</a> element. Suppose for example that, rather than simply indicating whether or not the example is considered valid by means of the values <span class="val">true</span> and <span class="val">false</span> we wish to provide a more nuanced indication, using encoded values such as A, B, and C. A declaration like the following might be appropriate: <div id="index-egXML-d52e150745" class="pre egXML_valid"><span class="element"><elementSpec <span class="attribute">ident</span>="<span class="attributevalue">eg</span>" <span class="attribute">module</span>="<span class="attributevalue">tagdocs</span>"<br /> <span class="attribute">mode</span>="<span class="attributevalue">change</span>"></span><br /> <span class="element"><attList></span><br /> <span class="element"><attDef <span class="attribute">ident</span>="<span class="attributevalue">valid</span>"<br /> <span class="attribute">ns</span>="<span class="attributevalue">http://www.example.com/ns/nonTEI</span>" <span class="attribute">mode</span>="<span class="attributevalue">add</span>"></span><br /> <span class="element"><desc></span>indicates the validity of the example by supplying one of three predefined<br /> codes for it.<span class="element"></desc></span><br /> <span class="element"><datatype></span><br /> <span class="element"><dataRef <span class="attribute">key</span>="<span class="attributevalue">teidata.enumerated</span>"/></span><br /> <span class="element"></datatype></span><br /> <span class="element"><valList <span class="attribute">type</span>="<span class="attributevalue">closed</span>"></span><br /> <span class="element"><valItem <span class="attribute">ident</span>="<span class="attributevalue">A</span>"></span><br /> <span class="element"><desc></span>validity is of the highest class<span class="element"></desc></span><br /> <span class="element"></valItem></span><br /> <span class="element"><valItem <span class="attribute">ident</span>="<span class="attributevalue">B</span>"></span><br /> <span class="element"><desc></span>validity is of the second highest class<span class="element"></desc></span><br /> <span class="element"></valItem></span><br /> <span class="element"><valItem <span class="attribute">ident</span>="<span class="attributevalue">C</span>"></span><br /> <span class="element"><desc></span>validity is of the lowest class<span class="element"></desc></span><br /> <span class="element"></valItem></span><br /> <span class="element"></valList></span><br /> <span class="element"></attDef></span><br /> <span class="element"></attList></span><br /><span class="element"></elementSpec></span></div></div><p>The same technique may be used to replace or extend the <a class="gi" title="(value list) contains one or more <valItem> elements defining possible values." href="ref-valList.html">valList</a> supplied as part of any attribute in the TEI scheme.</p></div><div class="div4" id="MDMDCL"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#MDMDAL"><span class="headingNumber">23.3.1.4 </span>Modification of Attribute and Attribute Value Lists</a></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#MDMDNE"><span class="headingNumber">23.3.1.6 </span>Addition of New Elements</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h5><span class="bookmarklink"><a class="bookmarklink" href="#MDMDCL" title="link to this section "><span class="invisible">TEI: Class Modification</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.3.1.5 </span><span class="head">Class Modification</span></h5><p>The concept of element classes was introduced in <a class="link_ptr" href="ST.html#STECCM" title="Model Classes"><span class="headingNumber">1.3.2 </span>Model Classes</a>; an understanding of it is fundamental to successful use of the TEI scheme. As noted there, we distinguish <span class="term">model classes</span>, the members of which all have structural similarity, from <span class="term">attribute classes</span>, the members of which simply share a set of attributes.</p><p>The part of an element specification which determines its class membership is an element called <a class="gi" title="specifies all the classes of which the documented element or class is a member or subclass." href="ref-classes.html">classes</a>. All classes to which the element belongs must be specified within this, using a <a class="gi" title="specifies class membership of the documented element or class." href="ref-memberOf.html">memberOf</a> element for each.</p><div class="p">To add an element to a class in which it is not already a member, all that is needed is to supply a new <a class="gi" title="specifies class membership of the documented element or class." href="ref-memberOf.html">memberOf</a> element within the <a class="gi" title="specifies all the classes of which the documented element or class is a member or subclass." href="ref-classes.html">classes</a> element for the element concerned. For example, to add an element to the <a class="link_odd" title="provides attributes which can be used to classify or subclassify elements in any way." href="ref-att.typed.html">att.typed</a> class, we include a declaration like the following: <div id="index-egXML-d52e150802" class="pre egXML_valid"><span class="element"><elementSpec <span class="attribute">ident</span>="<span class="attributevalue">eg</span>" <span class="attribute">module</span>="<span class="attributevalue">tagdocs</span>"<br /> <span class="attribute">mode</span>="<span class="attributevalue">change</span>" <span class="attribute">ns</span>="<span class="attributevalue">http://www.example.com/ns/nonTEI</span>"></span><br /> <span class="element"><classes <span class="attribute">mode</span>="<span class="attributevalue">change</span>"></span><br /> <span class="element"><memberOf <span class="attribute">key</span>="<span class="attributevalue">att.typed</span>"/></span><br /> <span class="element"></classes></span><br /><span class="element"></elementSpec></span></div> Any existing class memberships for the element being changed are not affected because the <span class="att">mode</span> attribute of the <a class="gi" title="specifies all the classes of which the documented element or class is a member or subclass." href="ref-classes.html">classes</a> element is set to <span class="val">change</span> (rather than its default value of <span class="val">replace</span>). Consequently, in this case, the <a class="gi" title="(example) contains any kind of illustrative example." href="ref-eg.html">eg</a> element retains its membership of the two classes (<a class="link_odd" title="groups common chunk- and inter-level elements." href="ref-model.common.html">model.common</a> and <a class="link_odd" title="groups elements containing images, formulae, and similar objects." href="ref-model.graphicLike.html">model.graphicLike</a>) to which it already belongs.</div><div class="p">Equally, to remove the attributes which an element inherits from its membership in some class, all that is needed is to remove the relevant <a class="gi" title="specifies class membership of the documented element or class." href="ref-memberOf.html">memberOf</a> element. For example, the element <a class="gi" title="contains a single-word, multi-word, or symbolic designation which is regarded as a technical term." href="ref-term.html">term</a> defined in the core module is a member of two attribute classes, <a class="link_odd" title="provides attributes which can be used to classify or subclassify elements in any way." href="ref-att.typed.html">att.typed</a> and <a class="link_odd" title="provides attributes for elements which may be independently associated with a particular declarable element within the header, thus overriding the inherited default for that element." href="ref-att.declaring.html">att.declaring</a>. It inherits the attributes <span class="att">type</span> and <span class="att">subtype</span> from the former, and the attribute <span class="att">decls</span> from the latter. To remove the last of these attributes from this element, we need to remove it from that class: <div id="index-egXML-d52e150853" class="pre egXML_valid"><span class="element"><elementSpec <span class="attribute">ident</span>="<span class="attributevalue">term</span>" <span class="attribute">module</span>="<span class="attributevalue">core</span>"<br /> <span class="attribute">mode</span>="<span class="attributevalue">change</span>"></span><br /> <span class="element"><classes <span class="attribute">mode</span>="<span class="attributevalue">change</span>"></span><br /> <span class="element"><memberOf <span class="attribute">key</span>="<span class="attributevalue">att.declaring</span>"<br /> <span class="attribute">mode</span>="<span class="attributevalue">delete</span>"/></span><br /> <span class="element"></classes></span><br /><span class="element"></elementSpec></span></div></div><div class="p">If the intention is to change the class membership of an element completely, rather than simply add or remove it to or from one or more classes, the value of the <span class="att">mode</span> attribute of <a class="gi" title="specifies all the classes of which the documented element or class is a member or subclass." href="ref-classes.html">classes</a> can be set to <span class="val">replace</span> (which is the default if no value is specified), indicating that the memberships indicated by its child <a class="gi" title="specifies class membership of the documented element or class." href="ref-memberOf.html">memberOf</a> elements are the only ones applicable. Thus the following declaration: <div id="index-egXML-d52e150872" class="pre egXML_valid"><span class="element"><elementSpec <span class="attribute">ident</span>="<span class="attributevalue">term</span>" <span class="attribute">module</span>="<span class="attributevalue">core</span>"<br /> <span class="attribute">mode</span>="<span class="attributevalue">change</span>" <span class="attribute">ns</span>="<span class="attributevalue">http://www.example.com/ns/nonTEI</span>"></span><br /> <span class="element"><classes <span class="attribute">mode</span>="<span class="attributevalue">replace</span>"></span><br /> <span class="element"><memberOf <span class="attribute">key</span>="<span class="attributevalue">att.interpLike</span>"/></span><br /> <span class="element"></classes></span><br /><span class="element"></elementSpec></span></div> would have the effect of removing the element <a class="gi" title="contains a single-word, multi-word, or symbolic designation which is regarded as a technical term." href="ref-term.html">term</a> from both its existing attribute classes, and adding it to the <a class="link_odd" title="provides attributes for elements which represent a formal analysis or interpretation." href="ref-att.interpLike.html">att.interpLike</a> class.</div><p>If however the <span class="att">mode</span> attribute is set to <span class="val">change</span>, the implication is that the memberships indicated by its child <a class="gi" title="specifies class membership of the documented element or class." href="ref-memberOf.html">memberOf</a> elements are to be combined with the existing memberships for the element.</p><div class="p">To change or remove attributes inherited from an attribute class for all members of the class (as opposed to specific members of that class), it is also possible to modify the class specification itself. For example, the class <a class="link_odd" title="provides rendering attributes common to all elements in the TEI encoding scheme." href="ref-att.global.rendition.html">att.global.rendition</a> defines several attributes which are available for all elements, namely <span class="att">rend</span>, <span class="att">style</span>, and <span class="att">rendition</span>. If we decide that we never wish to use the <span class="att">rend</span> attribute, the simplest way of removing it is to supply a modified class specification for <a class="link_odd" title="provides rendering attributes common to all elements in the TEI encoding scheme." href="ref-att.global.rendition.html">att.global.rendition</a> as follows: <div id="index-egXML-d52e150916" class="pre egXML_valid"><span class="element"><classSpec <span class="attribute">ident</span>="<span class="attributevalue">att.global.rendition</span>"<br /> <span class="attribute">type</span>="<span class="attributevalue">atts</span>" <span class="attribute">mode</span>="<span class="attributevalue">change</span>"></span><br /> <span class="element"><attList></span><br /> <span class="element"><attDef <span class="attribute">ident</span>="<span class="attributevalue">rend</span>" <span class="attribute">mode</span>="<span class="attributevalue">delete</span>"/></span><br /> <span class="element"></attList></span><br /><span class="element"></classSpec></span></div> Because the <span class="att">mode</span> attribute on the <a class="gi" title="(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." href="ref-classSpec.html">classSpec</a> defining the attributes inherited through membership of this class has the value <span class="val">change</span>, any of its existing identifiable components not specified in the modification above will remain unchanged. The only effect will therefore be to delete the <span class="att">rend</span> attribute from the class, and hence from all elements which are members of the class.</div><p>The classes used in the TEI scheme are further discussed in chapter <a class="link_ptr" href="ST.html" title="3"><span class="headingNumber">1 </span>The TEI Infrastructure</a>. Note in particular that classes are themselves classified: the attributes inherited by a member of attribute class A may come to it directly from that class, or from another class of which A is itself a member. For example, the class <a class="link_odd" title="provides attributes common to all elements in the TEI encoding scheme." href="ref-att.global.html">att.global</a> is itself a member of the classes <a class="link_odd" title="provides a set of attributes for hypertextual linking." href="ref-att.global.linking.html">att.global.linking</a> and <a class="link_odd" title="provides additional global attributes for associating specific analyses or interpretations with appropriate portions of a text." href="ref-att.global.analytic.html">att.global.analytic</a>. By default, these two classes are predefined as empty. However, if (for example) the <span class="ident-module">linking</span> module is included in a schema, a number of attributes (<span class="att">corresp</span>, <span class="att">sameAs</span>, etc.) are defined as members of the <a class="link_odd" title="provides a set of attributes for hypertextual linking." href="ref-att.global.linking.html">att.global.linking</a> class. All elements which are members of <a class="link_odd" title="provides attributes common to all elements in the TEI encoding scheme." href="ref-att.global.html">att.global</a> will then inherit these new attributes (see further section <a class="link_ptr" href="ST.html#STECAT" title="Attribute Classes"><span class="headingNumber">1.3.1 </span>Attribute Classes</a>). A new attribute may thus be added to the global class in two ways: either by adding it to the <a class="gi" title="contains documentation for all the attributes associated with this element, as a series of <attDef> elements." href="ref-attList.html">attList</a> defined within the class specification for <a class="link_odd" title="provides attributes common to all elements in the TEI encoding scheme." href="ref-att.global.html">att.global</a>; or by defining a new attribute class, and changing the class membership of the <a class="link_odd" title="provides attributes common to all elements in the TEI encoding scheme." href="ref-att.global.html">att.global</a> class to reference it.</p><p>Such global changes should be undertaken with caution: in general removing existing non-mandatory attributes from a class will always be a clean modification, in the same way as removing non-mandatory elements. Adding a new attribute to a class however can be a clean modification only if the new attribute is labelled as belonging to some namespace other than the TEI.</p><p>The same mechanisms are available for modification of model classes. Care should be taken when modifying the model class membership of existing elements since model class membership is what determines the content model of most elements in the TEI scheme, and a small change may have unintended consequences. </p></div><div class="div4" id="MDMDNE"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#MDMDCL"><span class="headingNumber">23.3.1.5 </span>Class Modification</a></li><li class="subtoc"></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h5><span class="bookmarklink"><a class="bookmarklink" href="#MDMDNE" title="link to this section "><span class="invisible">TEI: Addition of New Elements</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.3.1.6 </span><span class="head">Addition of New Elements</span></h5><p>To add a completely new element into a schema involves providing a complete element specification for it. It is recommended that the <a class="gi" title="specifies all the classes of which the documented element or class is a member or subclass." href="ref-classes.html">classes</a> element of this new declaration should include a reference to at least one TEI model class. Without such a reference, the new element would not otherwise be referenced by the content model of any other TEI element, and would therefore be inaccessible within a TEI document. It is also possible to modify the content models of one or more existing elements to refer to the new element explicitly, as discussed in <a class="link_ptr" href="USE.html#MDMDCM" title="Modification of Content Models"><span class="headingNumber">23.3.1.3 </span>Modification of Content Models</a> but this will generally be less convenient.</p><div class="p">For example, the three elements <a class="gi" title="(bibliographic citation) contains a loosely-structured bibliographic citation of which the sub-components may or may not be explicitly tagged." href="ref-bibl.html">bibl</a>, <a class="gi" title="(fully-structured bibliographic citation) contains a fully-structured bibliographic citation, in which all components of the TEI file description are present." href="ref-biblFull.html">biblFull</a>, and <a class="gi" title="(structured bibliographic citation) contains a structured bibliographic citation, in which only bibliographic sub-elements appear and in a specified order." href="ref-biblStruct.html">biblStruct</a> are all defined as members of the class <a class="link_odd" title="groups elements containing a bibliographic description." href="ref-model.biblLike.html">model.biblLike</a>. To add a fourth member (say <span class="gi"><myBibl></span>) to this class, we need to include in the <a class="gi" title="(element specification) documents the structure, content, and purpose of a single element type." href="ref-elementSpec.html">elementSpec</a> defining our new element a <a class="gi" title="specifies class membership of the documented element or class." href="ref-memberOf.html">memberOf</a> element which nominates the intended class: <div id="index-egXML-d52e151014" class="pre egXML_valid"><span class="element"><elementSpec <span class="attribute">ident</span>="<span class="attributevalue">myBibl</span>" <span class="attribute">mode</span>="<span class="attributevalue">add</span>"<br /> <span class="attribute">ns</span>="<span class="attributevalue">http://www.example.com/ns/nonTEI</span>"></span><br /> <span class="element"><classes></span><br /> <span class="element"><memberOf <span class="attribute">key</span>="<span class="attributevalue">model.biblLike</span>"/></span><br /> <span class="element"></classes></span><br /><span class="comment"><!-- other parts of the new declaration here --></span><br /><span class="element"></elementSpec></span></div> The other parts of this declaration will typically include a description for the new element and information about its content model, its attributes, etc., as further described in <a class="link_ptr" href="TD.html" title="27"><span class="headingNumber">22 </span>Documentation Elements</a>.</div></div></div><div class="div3" id="MDNS"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#MDMD"><span class="headingNumber">23.3.1 </span>Kinds of Modification</a></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#MDDO"><span class="headingNumber">23.3.3 </span>Documenting the Modification</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h4><span class="bookmarklink"><a class="bookmarklink" href="#MDNS" title="link to this section "><span class="invisible">TEI: Modification and Namespaces</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.3.2 </span><span class="head">Modification and Namespaces</span></h4><p>All the elements defined by the TEI scheme are labelled as belonging to a single <span class="term">namespace</span>, maintained by the TEI and with the URI <span class="val">http://www.tei-c.org/ns/1.0</span>.<span id="Note127_return"><a class="notelink" title="This is not strictly the case, since the element egXML used to represent TEI examples has its own namespace, http://www.tei-c.org/ns/Examples; this is…" href="#Note127"><sup>90</sup></a></span> Only elements which are unmodified or which have undergone a clean modification may use this namespace. Note however that TEI-defined attributes are not associated with any namespace. </p><p>This implies that any other modification (including a renaming or reversible modification) must either specify a different namespace or specify no namespace at all. The <span class="att">ns</span> attribute is provided on elements <a class="gi" title="(schema specification) generates a TEI-conformant schema and documentation for it." href="ref-schemaSpec.html">schemaSpec</a>, <a class="gi" title="(element specification) documents the structure, content, and purpose of a single element type." href="ref-elementSpec.html">elementSpec</a>, and <a class="gi" title="(attribute definition) contains the definition of a single attribute." href="ref-attDef.html">attDef</a> for this purpose.</p><div class="p">Suppose, for example, that we wish to add a new attribute <span class="att">topic</span> to the existing TEI element <a class="gi" title="(paragraph) marks paragraphs in prose." href="ref-p.html">p</a>. In the absence of namespace considerations, this would be an unclean modification, since <a class="gi" title="(paragraph) marks paragraphs in prose." href="ref-p.html">p</a> does not currently have such an attribute. The most appropriate action is to explicitly attach the new attribute to a new namespace by a declaration such as the following: <div id="index-egXML-d52e151068" class="pre egXML_invalid"><span class="element"><elementSpec <span class="attribute">ident</span>="<span class="attributevalue">p</span>" <span class="attribute">mode</span>="<span class="attributevalue">change</span>"></span><br /> <span class="element"><attList></span><br /> <span class="element"><attDef <span class="attribute">ident</span>="<span class="attributevalue">topic</span>" <span class="attribute">mode</span>="<span class="attributevalue">add</span>"<br /> <span class="attribute">ns</span>="<span class="attributevalue">http://www.example.org/ns/nonTEI</span>"></span><br /> <span class="element"><desc></span>indicates the topic of a TEI paragraph<span class="element"></desc></span><br /> <span class="element"><datatype></span><br /><span class="comment"><!-- ... --></span><br /> <span class="element"></datatype></span><br /> <span class="element"></attDef></span><br /> <span class="element"></attList></span><br /><span class="element"></elementSpec></span></div></div><div class="p">Document instances using a schema derived from this ODD can now indicate clearly the status of this attribute: <div id="index-egXML-d52e151078" class="pre egXML_valid"><span class="element"><div<br /> xmlns:my="http://www.example.org/ns/nonTEI"></span><br /><span class="comment"><!-- ... --></span><br /> <span class="element"><p <span class="attribute">n</span>="<span class="attributevalue">12</span>" <span class="attribute">my:topic</span>="<span class="attributevalue">rabbits</span>"></span>Flopsy, Mopsy, Cottontail, and Peter...<span class="element"></p></span><br /><span class="element"></div></span></div></div><p>Since <span class="att">topic</span> is explicitly labelled as belonging to something other than the TEI namespace, we regard the modification which introduced it as clean. A namespace-aware processor will be able to validate those elements in the TEI namespace against the unmodified schema.<span id="Note128_return"><a class="notelink" title="Full namespace support does not exist in the DTD language, and therefore these techniques are available only to users of more modern schema languages …" href="#Note128"><sup>91</sup></a></span></p><p>Similar considerations apply when modification is made to the content model or some other aspect of an element, or when a new element is declared. Clean modification requires that all such changes be explicitly labelled as belonging to some non-TEI namespace or to no namespace at all.</p><div class="p">If the <span class="att">ns</span> attribute is supplied on a <a class="gi" title="(schema specification) generates a TEI-conformant schema and documentation for it." href="ref-schemaSpec.html">schemaSpec</a> element, it identifies the namespace applicable to all components of the schema being specified. Even if such a schema includes unmodified modules from the TEI namespace, the elements contained by such modules will now be regarded as belonging to the namespace specified on the <a class="gi" title="(schema specification) generates a TEI-conformant schema and documentation for it." href="ref-schemaSpec.html">schemaSpec</a>. This can be useful if it is desired simply to avoid namespace processing. For example, the following schema specification results in a schema called <span class="ident">noName</span> which has no namespace, even though it comprises declarations from the TEI <span class="ident-module">header</span> module: <div id="index-egXML-d52e151110" class="pre egXML_valid"><span class="element"><schemaSpec <span class="attribute">ns</span>="<span class="attributevalue"></span>" <span class="attribute">ident</span>="<span class="attributevalue">noName</span>"></span><br /> <span class="element"><moduleRef <span class="attribute">key</span>="<span class="attributevalue">header</span>"/></span><br /><span class="comment"><!-- ... --></span><br /><span class="element"></schemaSpec></span></div></div><p>In addition to the TEI canonical namespace mentioned above, the TEI may also define namespaces for approved translations of the TEI scheme into other languages. These may be used as appropriate to indicate that a customization uses a standardized set of renamings. The namespace for such translations is the same as that for the canonical namespace, suffixed by the appropriate ISO language identifier (<a class="link_ptr" href="CH.html#CHSH" title="Language Identification"><span class="headingNumber">vi.1. </span>Language Identification</a>). A schema specification using the Chinese translation, for example, would use the namespace <span class="ident-ns">http://www.tei-c.org/ns/1.0/zh</span></p></div><div class="div3" id="MDDO"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#MDNS"><span class="headingNumber">23.3.2 </span>Modification and Namespaces</a></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#MDlite"><span class="headingNumber">23.3.4 </span>Examples of Modification </a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h4><span class="bookmarklink"><a class="bookmarklink" href="#MDDO" title="link to this section "><span class="invisible">TEI: Documenting the Modification</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.3.3 </span><span class="head">Documenting the Modification</span></h4><p>The elements used to define a TEI customization (<a class="gi" title="(schema specification) generates a TEI-conformant schema and documentation for it." href="ref-schemaSpec.html">schemaSpec</a>, <a class="gi" title="(module reference) references a module which is to be incorporated into a schema." href="ref-moduleRef.html">moduleRef</a>, <a class="gi" title="(element specification) documents the structure, content, and purpose of a single element type." href="ref-elementSpec.html">elementSpec</a>, etc.) will typically be used within a TEI document which supplies further information about the intended use of the new schema, the meaning and application of any new or modified elements within it, and so on. This document will typically conform to a TEI (or other) schema which includes the module described in chapter <a class="link_ptr" href="TD.html" title="27"><span class="headingNumber">22 </span>Documentation Elements</a>.<span id="Note129_return"><a class="notelink" title="This module can be used to document any XML schema, and has indeed been used to document several non-TEI schemas." href="#Note129"><sup>92</sup></a></span></p><p>Where the customization to be documented simply consists in a selection of modules, perhaps with some deletion of unwanted elements or attributes, the documentation need not specify anything further. Even here however it may be considered worthwhile to replace some of the semantic information provided by the unmodified TEI specification. For example, the <a class="gi" title="(description) contains a brief description of the object documented by its parent element, typically a documentation element or an entity." href="ref-desc.html">desc</a> element of an unmodified TEI <a class="gi" title="(element specification) documents the structure, content, and purpose of a single element type." href="ref-elementSpec.html">elementSpec</a> may describe an element in terms more general than appropriate to a particular project, or the <a class="gi" title="groups an example demonstrating the use of an element along with optional paragraphs of commentary." href="ref-exemplum.html">exemplum</a> elements within it may not illustrate the project's actual intended usage of the element, or the <a class="gi" title="contains any commentary or discussion about the usage of an element, attribute, class, or entity not otherwise documented within the containing element." href="ref-remarks.html">remarks</a> element may contain discussions of matters irrelevant to the project. These elements may therefore be replaced or deleted within an <a class="gi" title="(element specification) documents the structure, content, and purpose of a single element type." href="ref-elementSpec.html">elementSpec</a> as necessary.</p><p>Radical revision is also possible. It is feasible to produce a modification in which the <a class="gi" title="(TEI header) supplies descriptive and declarative metadata associated with a digital resource or set of resources." href="ref-teiHeader.html">teiHeader</a> or <a class="gi" title="contains a single text of any kind, whether unitary or composite, for example a poem or drama, a collection of essays, a novel, a dictionary, or a corpus sample." href="ref-text.html">text</a> elements are not required, or in which any other rule stated in these Guidelines is either not enforced or not enforceable. In fact, the mechanism, if used in an extreme way, permits replacement of all that the TEI has to say about every component of its scheme. Such revisions would result in documents that are not TEI-conformant in even the broadest sense, and it is not intended that encoders use the mechanism in this way. We discuss exactly what is meant by the concept of <span class="term">TEI conformance</span> in the next section, <a class="link_ptr" href="USE.html#CF" title="Conformance"><span class="headingNumber">23.4 </span>Conformance</a>.</p></div><div class="div3" id="MDlite"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#MDDO"><span class="headingNumber">23.3.3 </span>Documenting the Modification</a></li><li class="subtoc"></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h4><span class="bookmarklink"><a class="bookmarklink" href="#MDlite" title="link to this section "><span class="invisible">TEI: Examples of Modification </span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.3.4 </span><span class="head">Examples of Modification </span></h4><p>Several examples of customizations of the TEI are provided as part of the standard release. They include the following: </p><dl><dt><span>tei_bare</span></dt><dd>The schema generated from this customization is the minimum needed for TEI Conformance. It provides only a handful of elements. </dd><dt><span>tei_all</span></dt><dd>The schema generated from this customization combines all available TEI modules, providing 568 elements.</dd><dt><span>tei_allPlus</span></dt><dd>The schema generated from this customization combines all available TEI modules with three other non-TEI vocabularies, specifically MathML, SVG, and XInclude.</dd></dl><p>It is unlikely that any project would wish to use any of these extremes unchanged. However, they form a useful starting point for customization, whether by removing modules from tei_all or tei_allPlus, or by replacing elements deleted from tei_bare. They also demonstrate how an ODD document may be constructed to provide a basic reference manual to accompany schemas generated from it.</p><p>Shortly after publication of the first edition of these Guidelines, as a demonstration of how the TEI encoding scheme might be adopted to meet 90% of the needs of 90% of the TEI user community, the TEI editors produced a brief tutorial defining one specific ‘clean’ modification of the TEI scheme, which they called TEI Lite. This tutorial and its associated DTD became very popular and are still available from the TEI web site at <a class="link_ptr" href="http://www.tei-c.org/Guidelines/Customization/Lite/"><span>http://www.tei-c.org/Guidelines/Customization/Lite/</span></a>. The tutorial and associated schema specification is also included as one of the exemplars provided with TEI P5.</p><p>An updated and expanded version of this schema known as <span class="ident">TEI simplePrint</span> was added to the Exemplars at release 3.1.0. The elements it defines have been modified to take advantage of the ‘processing model’ features (see further <a class="link_ptr" href="TD.html#TDPM" title="Processing Models"><span class="headingNumber">22.5.5 </span>Processing Models</a>) introduced to the Guidelines at release 3.0.0.</p><p>The exemplars provided with TEI P5 also include a customization file from which a schema for the validation of other customization files may be generated. This ODD, called tei_odds, combines the four basic modules with the tagdocs, dictionaries, gaiji, linking, and figures modules and also provides facilities for including RELAX NG or Schematron code within a document. </p></div></div><div class="div2" id="CF"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#MD"><span class="headingNumber">23.3 </span>Customization</a></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#IM"><span class="headingNumber">23.5 </span>Implementation of an ODD System</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h3><span class="bookmarklink"><a class="bookmarklink" href="#CF" title="link to this section "><span class="invisible">TEI: Conformance</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.4 </span><span class="head">Conformance</span></h3><p>The notion of <span class="term">TEI Conformance</span> is intended to assist in the description of the format and contents of a particular XML document instance or set of documents. It may be found useful in such situations as: </p><ul class="bulleted"><li class="item">interchange or integration of documents amongst different researchers or users; </li><li class="item">software specifications for TEI-aware processing tools; </li><li class="item">agreements for the deposit of texts in, and distribution of texts from, archives; </li><li class="item">specifying the form of documents to be produced by or for a given project. </li></ul><p> It is not intended to provide any other evaluation, for example of scholarly merit, intellectual integrity, or value for money. A document may be of major intellectual importance and yet not be TEI-conformant; a TEI-conformant document may be of no scholarly value whatsoever.</p><p>In this section we explore several aspects of conformance, and in particular attempt to define how the term <span class="term">TEI-conformant</span> should be used. The terminology defined here should be considered normative: users and implementors of the TEI Guidelines should use the phrases ‘TEI-conformant’ and ‘TEI Extension’ only in the senses given and with the usages described.</p><p>A document is <span class="term">TEI-conformant</span> if it: </p><ul class="bulleted"><li class="item">is a well-formed XML document (<a class="link_ptr" href="USE.html#CFWF" title="Wellformedness Criterion"><span class="headingNumber">23.4.1 </span>Well-formedness Criterion</a>)</li><li class="item">can be validated against a <span class="term">TEI Schema</span>, that is, a schema derived from the TEI Guidelines (<a class="link_ptr" href="USE.html#CFVL" title="Validation Constraint"><span class="headingNumber">23.4.2 </span>Validation Constraint</a>)</li><li class="item">conforms to the TEI Abstract Model (<a class="link_ptr" href="USE.html#CFAM" title="Conformance to the TEI Abstract Model"><span class="headingNumber">23.4.3 </span>Conformance to the TEI Abstract Model</a>)</li><li class="item">uses the <span class="term">TEI Namespace</span> (and other namespaces where relevant) correctly (<a class="link_ptr" href="USE.html#CFNS" title="Use of the TEI Namespace"><span class="headingNumber">23.4.4 </span>Use of the TEI Namespace</a>)</li><li class="item">is documented by means of a TEI-conformant <span class="term">ODD file</span> (<a class="link_ptr" href="USE.html#CFOD" title="Documentation Constraint"><span class="headingNumber">23.4.5 </span>Documentation Constraint</a>) which refers to the TEI Guidelines</li></ul><p> Each of these criteria is discussed in more detail below.</p><p>A document is said to use a <span class="term">TEI Extension</span> if it is a well-formed XML document which is valid against a TEI Schema which contains additional distinctions, representing concepts not present in the TEI Abstract Model, and therefore not documented in these Guidelines. Such a document cannot, in general, be algorithmically conformant since it cannot be automatically transformed without loss of information. However, since one of the goals of the TEI is to support extensions and modifications, it should not be assumed that no TEI document can include extensions: an extension which is expressed by means of the recommended mechanisms is also a TEI document provided that those parts of it which are not extensions are TEI-conformant.</p><p>A TEI-conformant document is said to follow <span class="term">TEI Recommended Practice</span> if, wherever these Guidelines prefer one encoding practice to another, the preferred practice is used.</p><div class="div3" id="CFWF"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#CFVL"><span class="headingNumber">23.4.2 </span>Validation Constraint</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h4><span class="bookmarklink"><a class="bookmarklink" href="#CFWF" title="link to this section "><span class="invisible">TEI: Well-formedness Criterion</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.4.1 </span><span class="head">Well-formedness Criterion</span></h4><p>These Guidelines mandate the use of well-formed XML as representation format. Documents must conform to the World Wide Web Consortium recommendation of the <span class="titlem">Extensible Markup Language (XML) 1.0 (Fourth Edition)</span> or successor editions found at <a class="link_ref" href="http://www.w3.org/TR/xml/">http://www.w3.org/TR/xml/</a>. Other ways of representing the concepts of the TEI Abstract Model are possible, and other representations may be considered appropriate for use in particular situations (for example, for data capture, or project-internal processing). But such alternative representations should not be considered in any way TEI-conformant.</p><p>Previous versions of these Guidelines used SGML as a representation format. With the release of P5, the only representation format supported by these Guidelines became valid XML; legacy documents in SGML format should therefore be converted using appropriate software.</p><p>A TEI-conformant document must use the TEI namespace, and therefore must also include an XML-conformant namespace declaration, as defined below (<a class="link_ptr" href="USE.html#CFNS" title="Use of the TEI Namespace"><span class="headingNumber">23.4.4 </span>Use of the TEI Namespace</a>).</p><p>The use of XML greatly reduces the need to consider hardware or software differences between processing environments when exchanging data. No special packing or interchange format is required for an XML document, beyond that defined by the W3C recommendations, and no special ‘interchange’ format is therefore proposed by these Guidelines. For discussion of encoding issues that may arise in the processing of special character sets or non-standard writing systems, see further chapter <a class="link_ptr" href="CH.html" title="4"><span class="headingNumber">vi. </span>Languages and Character Sets</a>.</p><p>In addition to the well-formedness criterion, the W3C defines the notion of a <span class="term">valid</span> document, as being a well-formed document which matches a specific set of rules or syntactic constraints, defined by a <span class="term">schema</span>. As noted above, TEI conformance implies that the schema used to determine validity of a given document should be derived from the present Guidelines, by means of an ODD which references and documents the schema fragments which these Guidelines define.</p></div><div class="div3" id="CFVL"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#CFWF"><span class="headingNumber">23.4.1 </span>Well-formedness Criterion</a></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#CFAM"><span class="headingNumber">23.4.3 </span>Conformance to the TEI Abstract Model</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h4><span class="bookmarklink"><a class="bookmarklink" href="#CFVL" title="link to this section "><span class="invisible">TEI: Validation Constraint</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.4.2 </span><span class="head">Validation Constraint</span></h4><p>All <span class="term">TEI-conformant</span> documents must validate against a schema file that has been derived from the published TEI Guidelines, combined and documented in the manner described in section <a class="link_ptr" href="USE.html#MD" title="Customization"><span class="headingNumber">23.3 </span>Customization</a>. We call the formal output of this process a <span class="term">TEI Schema</span>.</p><p>The TEI does not mandate use of any particular schema language, only that this schema<span id="Note130_return"><a class="notelink" title="Here and elsewhere we use the word schema to refer to any formal document grammar language, irrespective of the formalism used to represent it." href="#Note130"><sup>93</sup></a></span> should have been generated from a <span class="term">TEI ODD file</span> that references the TEI Guidelines. Currently available tools permit the expression of schemas in any or all of the XML DTD language, W3C XML Schema, and RELAX NG (both compact and XML formats). Some of what is syntactically possible using the ODD formalism cannot be represented by all schema languages; and there are some features of some schema languages which have no counterpart in ODD. No single schema language fully captures all the constraints implied by conformance to the TEI Abstract Model. A document which is valid according to a TEI schema represented using one schema language may not be valid against the same schema expressed in other languages; for example, the DTD language does not support namespaces. </p><p>As noted in section <a class="link_ptr" href="USE.html#MD" title="Customization"><span class="headingNumber">23.3 </span>Customization</a>, many varieties of TEI schema are possible and not all of them are necessarily <span class="term">TEI-conformant</span>; derivation from an ODD is a necessary but not a sufficient condition for TEI Conformance.</p></div><div class="div3" id="CFAM"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#CFVL"><span class="headingNumber">23.4.2 </span>Validation Constraint</a></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#CFNS"><span class="headingNumber">23.4.4 </span>Use of the TEI Namespace</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h4><span class="bookmarklink"><a class="bookmarklink" href="#CFAM" title="link to this section "><span class="invisible">TEI: Conformance to the TEI Abstract Model</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.4.3 </span><span class="head">Conformance to the TEI Abstract Model</span></h4><p>The <span class="term">TEI Abstract Model</span> is the conceptual schema instantiated by the TEI Guidelines. These Guidelines define, both formally and informally, a set of abstract concepts such as <span class="q">‘paragraph’</span> or <span class="q">‘heading’</span>, and their structural relationships, for example stating that ‘paragraph’s do not contain ‘heading’s. These Guidelines also define classes of elements, which have both semantic and structural properties in common. Those semantic and structural properties are also a part of the TEI Abstract Model; the class membership of an existing TEI element cannot therefore be changed without changing the model. Elements can however be removed from a class by deletion, and new non-TEI elements within their own namespaces can be added to existing TEI classes.</p><div class="div4" id="CFAMsc"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#CFAMmc"><span class="headingNumber">23.4.3.2 </span>Mandatory Components of a TEI Document</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h5><span class="bookmarklink"><a class="bookmarklink" href="#CFAMsc" title="link to this section "><span class="invisible">TEI: Semantic Constraints</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.4.3.1 </span><span class="head">Semantic Constraints</span></h5><p>It is an important condition of TEI conformance that elements defined in the TEI Guidelines as having one specific meaning should not be used with another. For example, the element <a class="gi" title="(verse line) contains a single, possibly incomplete, line of verse." href="ref-l.html">l</a> is defined in the TEI Guidelines as containing a line of verse. A schema in which it is redefined to mean a typographic line, or an ordered queue of objects of some kind, cannot therefore be TEI-conformant, whatever its other properties.</p><p>The semantics of elements defined in the TEI Guidelines are conveyed in a number of ways, ranging from formally verifiable datatypes to informal descriptive prose. In addition, a mapping between TEI elements and concepts in other conceptual models may be provided by the <a class="gi" title="(equivalent) specifies a component which is considered equivalent to the parent element, either by co-reference, or by external link." href="ref-equiv.html">equiv</a> element where this is available.</p><p>A schema which shares equivalent concepts to those of the TEI conceptual model may be mappable to the TEI Schema by means of such a mechanism. For example, the concept of paragraph expressed in the TEI scheme by the <a class="gi" title="(paragraph) marks paragraphs in prose." href="ref-p.html">p</a> element is probably the same concept as that expressed in the DocBook scheme by the <span class="gi"><para></span> element. Such areas of overlap facilitate interoperability, because elements from one namespace may be readily integrated with those from another, but do not affect the definition of conformance.</p><p>A document is said to conform to the <span class="term">TEI Abstract Model</span> if features for which an encoding is proposed by the TEI Guidelines are encoded within it using the markup and other syntactic properties defined by means of a valid <span class="term">TEI-conformant</span> schema. Hence, even though the names of elements or attributes may vary, a TEI-conformant document must respect the TEI Semantic Model, and be valid with respect to a TEI-conformant Schema. Although it may be possible to transform a document which follows the <span class="term">TEI Abstract Model</span> into a <span class="term">TEI-conformant</span> document, such a document is not itself necessarily conformant.</p><p>As noted above, the notion of semantic conformance cannot be completely enforced in a formal way. The TEI conceptual model is expressed by means of formal specification in a customization file, by means of descriptive prose in the body of these Guidelines, and implicitly by examples of usage. Any inconsistency between, for example, the text of these Guidelines and a part of a specification should be considered an error and reported to the TEI Council for correction. </p></div><div class="div4" id="CFAMmc"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#CFAMsc"><span class="headingNumber">23.4.3.1 </span>Semantic Constraints</a></li><li class="subtoc"></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h5><span class="bookmarklink"><a class="bookmarklink" href="#CFAMmc" title="link to this section "><span class="invisible">TEI: Mandatory Components of a TEI Document</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.4.3.2 </span><span class="head">Mandatory Components of a TEI Document</span></h5><p>It is a long-standing requirement for any <span class="term">TEI-conformant</span> document that it should contain a <a class="gi" title="(TEI header) supplies descriptive and declarative metadata associated with a digital resource or set of resources." href="ref-teiHeader.html">teiHeader</a> element. To be more specific a <span class="term">TEI-conformant</span> document must contain </p><ul><li class="item">a single <a class="gi" title="(TEI header) supplies descriptive and declarative metadata associated with a digital resource or set of resources." href="ref-teiHeader.html">teiHeader</a> element followed by one or more elements from the <span class="ident">model.resourceLike</span> class; or</li><li class="item">in the case of a corpus or collection, a single overall <a class="gi" title="(TEI header) supplies descriptive and declarative metadata associated with a digital resource or set of resources." href="ref-teiHeader.html">teiHeader</a> element followed by a series of <a class="gi" title="(TEI document) contains a single TEI-conformant document, combining a single TEI header with one or more members of the model.resourceLike class. Multiple <TEI> elements may be combined to form a <teiCorpus> element." href="ref-TEI.html">TEI</a> elements each with its own <a class="gi" title="(TEI header) supplies descriptive and declarative metadata associated with a digital resource or set of resources." href="ref-teiHeader.html">teiHeader</a></li></ul><p> All <a class="gi" title="(TEI header) supplies descriptive and declarative metadata associated with a digital resource or set of resources." href="ref-teiHeader.html">teiHeader</a> elements in a <span class="term">TEI-conformant</span> document must include elements for: </p><dl><dt><span>Title Statement</span></dt><dd>This should include the title of the TEI document expressed using a <a class="gi" title="(title statement) groups information about the title of a work and those responsible for its content." href="ref-titleStmt.html">titleStmt</a> element.</dd><dt><span>Publication Statement</span></dt><dd>This should include the place and date of publication or distribution of the TEI document, expressed using the <a class="gi" title="(publication statement) groups information concerning the publication or distribution of an electronic or other text." href="ref-publicationStmt.html">publicationStmt</a> element.</dd><dt><span>Source Statement</span></dt><dd>For a document derived from some previously existing document, this must include a bibliographic description of that source. For a document not so derived, this must include a brief statement that the document has no pre-existing source. In either case, this will be expressed using the <a class="gi" title="(source description) describes the source from which an electronic text was derived or generated, typically a bibliographic description in the case of a digitized text, or a phrase such as "born digital" for a text which has no previous existence." href="ref-sourceDesc.html">sourceDesc</a> element.</dd></dl></div></div><div class="div3" id="CFNS"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#CFAM"><span class="headingNumber">23.4.3 </span>Conformance to the TEI Abstract Model</a></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#CFOD"><span class="headingNumber">23.4.5 </span>Documentation Constraint</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h4><span class="bookmarklink"><a class="bookmarklink" href="#CFNS" title="link to this section "><span class="invisible">TEI: Use of the TEI Namespace</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.4.4 </span><span class="head">Use of the <span class="term">TEI Namespace</span></span></h4><p>The Namespaces Recommendation of the W3C (<a class="link_ptr" href="BIB.html#NAMESPACES" title="Tim Bray Dave Hollander Andrew Laymon Richard Tobin Namespaces in XML 1.0 (second edition)W3C16 August 2006">Bray et al. (eds.) (2006)</a>) provides a way for an XML document to combine markup from different vocabularies without risking name collision and consequent processing difficulties. While the scope of the TEI is large, there are many areas in which it makes no particular recommendation, or where it recommends that other defined markup schemes should be adopted, such as graphics or mathematics. It is also considered desirable that users of other markup schemes should be able to integrate documents using TEI markup with their own system. To meet these objectives without compromising the reliability of its encoding, a TEI-conformant document is required to make appropriate use of the TEI namespace.</p><p>Essentially all elements in a TEI Schema which represents concepts from the TEI Abstract Model belong to the TEI namespace, <span class="ident-ns">http://www.tei-c.org/ns/1.0</span>, maintained by the TEI. A TEI-conformant document is required to declare the namespace for all the elements it contains whether these come from the TEI namespace or from other schemes.</p><p>A TEI Schema may be created which assigns TEI elements to some other namespace, or to no namespace at all. A document using such a schema must be regarded as a TEI extension and cannot be considered TEI-conformant. A document which places non-TEI elements or attributes within the TEI namespace cannot be TEI-conformant; such practices are strongly deprecated as they may lead to serious difficulties for processing or interchange.</p></div><div class="div3" id="CFOD"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#CFNS"><span class="headingNumber">23.4.4 </span>Use of the TEI Namespace</a></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#CFCATSCH"><span class="headingNumber">23.4.6 </span>Varieties of TEI Conformance</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h4><span class="bookmarklink"><a class="bookmarklink" href="#CFOD" title="link to this section "><span class="invisible">TEI: Documentation Constraint</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.4.5 </span><span class="head">Documentation Constraint</span></h4><p>As noted in <a class="link_ptr" href="USE.html#CFVL" title="Validation Constraint"><span class="headingNumber">23.4.2 </span>Validation Constraint</a> above, a TEI Schema can only be generated from a TEI ODD, which also serves to document the semantics of the elements defined by it. A TEI-conformant document should therefore always be accompanied by (or refer to) a valid <span class="term">TEI ODD file</span> specifying which modules, elements, classes, etc. are in use together with any modifications or renamings applied, and from which a TEI Schema can be generated to validate the document. The TEI supplies a number of predefined <span class="term">TEI Customization exemplar ODD files</span> and the schemas already generated from them (see <a class="link_ptr" href="USE.html#MDlite" title="Examples of Modification"><span class="headingNumber">23.3.4 </span>Examples of Modification </a>), but most projects will typically need to customize the TEI beyond what these examples provide. It is assumed, for example, that most projects will customize the TEI scheme by removing those elements that are not needed for the texts they are encoding, and by providing further constraints on the attribute values and element content models the TEI provides. All such customizations must be specified by means of a valid <span class="term">TEI ODD</span> file.</p><p>As different sorts of customization have different implications for the interchange and interoperability of TEI documents, it cannot be assumed that every customization will necessarily result in a schema that validates only TEI-conformant documents. The ODD language permits modifications which conflict with the TEI Abstract Model, even though observing this model is a requirement for TEI Conformance. The ODD language can in fact be used to describe many kinds of markup scheme, including schemes which have nothing to do with the TEI at all. </p><p>Equally, it is possible to construct a TEI Schema which is identical to that derived from a given TEI ODD file without using the ODD scheme. A schema can constructed simply by combining the predefined schema language fragments corresponding with the required set of TEI modules and other statements in the relevant schema language. However, the status of such a schema with respect to the <span class="ident-schema">tei_all</span> schema cannot in general be easily determined; it may therefore be impractical to determine whether such a schema represents a clean modification or an extension. This is one reason for making the presence of a TEI ODD file a requirement for conformance.</p></div><div class="div3" id="CFCATSCH"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#CFOD"><span class="headingNumber">23.4.5 </span>Documentation Constraint</a></li><li class="subtoc"></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h4><span class="bookmarklink"><a class="bookmarklink" href="#CFCATSCH" title="link to this section "><span class="invisible">TEI: Varieties of TEI Conformance</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.4.6 </span><span class="head">Varieties of TEI Conformance</span></h4><p>The conformance status of a given document may be assessed by answering the following questions, in the order indicated: </p><ol class="numbered"><li class="item">Is it a valid XML document, for which a TEI Schema exists? If not, then the document cannot be considered TEI-conformant in any sense.</li><li class="item">Is the document accompanied by a TEI-conformant ODD specification describing its markup scheme and intended semantics? If not, then the document can only be considered TEI-conformant if it validates against a predefined TEI Schema and conforms to the TEI abstract model.</li><li class="item">Does the markup in the document correctly represent the TEI abstract model? Though difficult to assess, this is essential to TEI conformance.</li><li class="item">Does the document claim that all of its elements come from some namespace other than the TEI (or no namespace)? If so, the document cannot be TEI-conformant.</li><li class="item">If the document claims to use the TEI namespace, in part or wholly, do the elements associated with that namespace in fact belong to it? If not, the document cannot be TEI-conformant; if so, and if all non-TEI elements and attributes are correctly associated with other namespaces, then the document may be TEI-conformant.</li><li class="item">Is the document valid according to a schema made by combining all TEI modules as well as valid according to the schema derived from its associated ODD specification? If so, the document is TEI-conformant. </li><li class="item">Is the document valid according to the schema derived from its associated ODD specification, but not according to <span class="ident-schema">tei_all</span>? If so, the document uses a TEI extension.</li><li class="item">Is it possible automatically to transform the document into a document which is valid according to <span class="ident-schema">tei_all</span>, using only information supplied in the accompanying ODD and without loss of information? If so, the document is TEI-conformant.</li></ol><p>In the following table, we examine more closely some specific, though imaginary, cases: </p><div class="table" id="tab-conformance"><table><tr class="label"><td></td><td>A</td><td>B </td><td>C</td><td>D</td><td>E </td><td>F</td><td>G</td><td>H</td></tr><tr><td>Conforms to TEI Abstract Model</td><td>Y</td><td>N</td><td>Y</td><td>Y</td><td>?</td><td>Y</td><td>N</td><td>?</td></tr><tr><td>Valid ODD present</td><td>Y</td><td>Y</td><td>Y</td><td>Y</td><td>Y</td><td>Y</td><td>Y</td><td>N</td></tr><tr><td>Uses only non-TEI namespace(s) or none</td><td>N</td><td>N</td><td>N</td><td>N</td><td>Y</td><td>N</td><td>Y</td><td>N</td></tr><tr><td>Uses TEI and other namespaces correctly</td><td>Y</td><td>Y</td><td>N</td><td>Y</td><td>N</td><td>Y</td><td>N</td><td>Y</td></tr><tr><td>Document is valid as a subset of <span class="ident-schema">tei_all</span></td><td>Y</td><td>N</td><td>Y</td><td>N</td><td>N</td><td>Y</td><td>N</td><td>Y</td></tr><tr><td>Document can be converted automatically to a form which is valid as a subset of <span class="ident-schema">tei_all</span></td><td>Y</td><td>N</td><td>Y</td><td>N</td><td>N</td><td>Y</td><td>N</td><td>?</td></tr></table></div><p>We assume firstly that each sample document assessed here is a well-formed XML document, and that it is valid against some schema. </p><p>The document in column A is TEI-conformant. Its tagging follows the TEI Abstract Model, both as regards syntactic constraints (its <a class="gi" title="(verse line) contains a single, possibly incomplete, line of verse." href="ref-l.html">l</a> elements appear within <a class="gi" title="(text division) contains a subdivision of the front, body, or back of a text." href="ref-div.html">div</a> elements and not the reverse) and semantic constraints (its <a class="gi" title="(verse line) contains a single, possibly incomplete, line of verse." href="ref-l.html">l</a> elements appear to contain verse lines rather than typographic ones). It is accompanied by a valid ODD which documents exactly how it uses the TEI. All the TEI-defined elements and attributes in the document are placed in the TEI namespace. The schema against which it is valid is a ‘clean’ subset of the <span class="ident-schema">tei_all</span> schema.</p><p>The document in column B is not a TEI document. Although it is accompanied by a valid TEI ODD, the resulting schema includes some ‘unclean’ modifications, and represents some concepts from the TEI Abstract Model using non-TEI elements; for example, it re-defines the content model of <a class="gi" title="(paragraph) marks paragraphs in prose." href="ref-p.html">p</a> to permit <a class="gi" title="(text division) contains a subdivision of the front, body, or back of a text." href="ref-div.html">div</a> within it, and it includes an element <span class="gi"><pageTrimming></span> which appears to have the same meaning as the existing TEI <a class="gi" title="(forme work) contains a running head (e.g. a header, footer), catchword, or similar material appearing on the current page." href="ref-fw.html">fw</a> element, but the equivalence is not made explicit in the ODD. It uses the TEI namespace correctly to identify the TEI elements it contains, but the ODD does not contain enough information automatically to convert its non-TEI elements into TEI equivalents.</p><p>The document in column C is TEI conformant. It is almost the same as the document in column A, except that the names of the elements used are not those specified for the TEI namespace. Because the ODD accompanying it contains an exact mapping for each element name (using the <a class="gi" title="(alternate identifier) supplies the recommended XML name for an element, class, attribute, etc. in some language." href="ref-altIdent.html">altIdent</a> element) and there are no name conflicts, it is possible to make an automatic conversion of this document.</p><p>The document in column D is a TEI Extension. It combines elements from its own namespace with unmodified TEI elements in the TEI namespace. Its usage of TEI elements conforms to the TEI Abstract Model. Its ODD defines a new <span class="gi"><blort></span> element which has no exact TEI equivalent, but which is assigned to an existing TEI class; consequently its schema is not a clean subset of <span class="ident-schema">tei_all</span>. If the associated ODD provided a way of mapping this element to an existing TEI element, then this would be TEI-conformant.</p><p>The document in column E is superficially similar to document D, but because it does not use any namespace declarations (or, equivalently, it assigns unmodified TEI elements to its own namespace), it may contain name collisions; there is no way of knowing whether a <a class="gi" title="(paragraph) marks paragraphs in prose." href="ref-p.html">p</a> within it is the same as the TEI's <a class="gi" title="(paragraph) marks paragraphs in prose." href="ref-p.html">p</a> or has some other meaning. The accompanying ODD file may be used to provide the human reader with information about equivalently named elements in the TEI namespace, and hence to determine whether the document is valid with respect to the TEI Abstract Model but this is not an automatable process. In particular, cases of apparent conflict (for example use of an element <a class="gi" title="(paragraph) marks paragraphs in prose." href="ref-p.html">p</a> to represent a concept not in the TEI Abstract Model but in the abstract model of some other system, whose namespace has been removed as well) cannot be reliably resolved. By our current definition therefore, this is not a TEI document.</p><p>The document in column F is TEI-conformant. The difference between it and that in column D is that the new element <span class="gi"><blort></span> which is used in this document is a specialization of an existing TEI element, and the ODD in which it is defined specifies the mapping (a <span class="gi"><my:blort></span> may be automatically converted to a <span class="tag"><tei:seg type="blort"></span>, for example). For this to work, however, the <span class="gi"><blort></span> must observe the same syntactic constraints as the <a class="gi" title="(arbitrary segment) represents any segmentation of text below the ‘chunk’ level." href="ref-seg.html">seg</a>; if it does not, this would also be a case of TEI Extension.</p><p>The document in column G is not a TEI document. Its structure is fully documented by a valid TEI ODD, but it does not claim to represent the TEI Abstract Model, does not use the TEI namespace, and is not intended to validate against any TEI schema. </p><p>The document in column H is very like that in column A, but it lacks an accompanying ODD. Instead, the schema used to validate it is produced simply by combining TEI schema fragments in the same way as an ODD processor would, given the ODD. If the resulting schema is a clean subset of <span class="ident-schema">tei_all</span>, such a document is indistinguishable from a TEI-conformant one, but there is no way of determining (without inspection) whether this is the case if any modification or extension has been applied. Its status is therefore, like that of Text E, impossible to determine.</p></div></div><div class="div2" id="IM"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#CF"><span class="headingNumber">23.4 </span>Conformance</a></li><li class="subtoc"></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h3><span class="bookmarklink"><a class="bookmarklink" href="#IM" title="link to this section "><span class="invisible">TEI: Implementation of an ODD System</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.5 </span><span class="head">Implementation of an ODD System</span></h3><p>This section specifies how a processing system may take advantage of the markup specification elements documented in chapter <a class="link_ptr" href="TD.html" title="27"><span class="headingNumber">22 </span>Documentation Elements</a> of these Guidelines in order to produce project specific user documentation, schemas in one or more schema languages, and validation tools for other processors.</p><p>The specifications in this section are illustrative but not normative. Its function is to further illustrate the intended scope and application of the elements documented in chapter <a class="link_ptr" href="TD.html" title="27"><span class="headingNumber">22 </span>Documentation Elements</a>, since it is believed that these may have application beyond the areas directly addressed by the TEI.</p><p>An ODD processing system has to accomplish two main tasks. A set of selections, deletions, changes, and additions supplied by an ODD customization (as described in <a class="link_ptr" href="USE.html#MD" title="Customization"><span class="headingNumber">23.3 </span>Customization</a>) must first be merged with the published TEI P5 ODD specifications. Next, the resulting unified ODD must be processed to produce the desired outputs.</p><p>An ODD processor is not required to do these two stages in sequence, but that may well be the simplest approach; the ODD processing tools currently provided by the TEI Consortium, which are also used to process the source of these Guidelines, adopt this approach.</p><div class="teidiv2" id="IM-unified"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#IMGS"><span class="headingNumber">23.5.2 </span>Generating Schemas</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h4><span class="bookmarklink"><a class="bookmarklink" href="#IM-unified" title="link to this section "><span class="invisible">TEI: Making a Unified ODD</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.5.1 </span><span class="head">Making a Unified ODD</span></h4><p>An ODD customization must contain a single <a class="gi" title="(schema specification) generates a TEI-conformant schema and documentation for it." href="ref-schemaSpec.html">schemaSpec</a> element, which defines the schema to be constructed. </p><ul class="specList"><li><span class="specList-elementSpec"><a href="ref-schemaSpec.html">schemaSpec</a></span> (schema specification) generates a TEI-conformant schema and documentation for it.<table class="specDesc"><tr><td class="Attribute"><span class="att">start</span></td><td>specifies entry points to the schema, i.e. which patterns may be used as the root of documents conforming to it.</td></tr><tr><td class="Attribute"><span class="att">prefix</span></td><td>specifies a default prefix which will be prepended to all patterns relating to TEI elements, unless otherwise stated.</td></tr><tr><td class="Attribute"><span class="att">targetLang</span></td><td>(target language) specifies which language to use when creating the objects in a schema if names for elements or attributes are available in more than one language</td></tr><tr><td class="Attribute"><span class="att">docLang</span></td><td>(documentation language) specifies which languages to use when creating documentation if the description for an element, attribute, class or macro is available in more than one language</td></tr></table></li></ul><p> Amongst other attributes inherited from the <a class="link_odd" title="provides the identifying attribute for elements which can be subsequently referenced by means of a @key attribute." href="ref-att.identified.html">att.identified</a> class, this element also carries a required <span class="att">ident</span> attribute. This provides a name for the generated schema, which other components of the processing system may use to refer to the schema being generated, e.g. in issuing error messages or as part of the generated output schema file or files. The <span class="att">ns</span> attribute may be used to specify the default namespace within which elements valid against the resulting schema belong, as discussed in <a class="link_ptr" href="USE.html#MDNS" title="Modification and Namespaces"><span class="headingNumber">23.3.2 </span>Modification and Namespaces</a>.</p><p>The <a class="gi" title="(schema specification) generates a TEI-conformant schema and documentation for it." href="ref-schemaSpec.html">schemaSpec</a> element contains an unordered series of specialized elements, each of which is of one of the following four types: </p><dl><dt><span>specifications</span></dt><dd>elements from the class <a class="link_odd" title="groups elements which generate declarations in some markup language in ODD documents." href="ref-model.oddDecl.html">model.oddDecl</a> (by default <a class="gi" title="(element specification) documents the structure, content, and purpose of a single element type." href="ref-elementSpec.html">elementSpec</a>, <a class="gi" title="(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." href="ref-classSpec.html">classSpec</a>, <a class="gi" title="(module specification) documents the structure, content, and purpose of a single module, i.e. a named and externally visible group of declarations." href="ref-moduleSpec.html">moduleSpec</a>, and <a class="gi" title="(macro specification) documents the function and implementation of a pattern." href="ref-macroSpec.html">macroSpec</a>); these must have a <span class="att">mode</span> attribute which determines how they will be processed.<span id="Note131_return"><a class="notelink" title="An ODD processor should recognize as erroneous such obvious inconsistencies as an attempt to include an elementSpec in add mode for an element which i…" href="#Note131"><sup>94</sup></a></span> If the value of <span class="att">mode</span> is <span class="val">add</span>, then the object is simply copied to the output, but if it is <span class="val">change</span>, <span class="val">delete</span>, or <span class="val">replace</span>, then it will be looked at by other parts of the process.</dd><dt><span>references to specifications</span></dt><dd><a class="gi" title="(reference to a specification group) indicates that the declarations contained by the <specGrp> referenced should be inserted at this point." href="ref-specGrpRef.html">specGrpRef</a> elements refer to <a class="gi" title="(specification group) contains any convenient grouping of specifications for use within the current module." href="ref-specGrp.html">specGrp</a> elements that occur elsewhere in this, or another, document. A <a class="gi" title="(specification group) contains any convenient grouping of specifications for use within the current module." href="ref-specGrp.html">specGrp</a> element, in turn, groups together a set of ODD specifications (among other things, including further <a class="gi" title="(reference to a specification group) indicates that the declarations contained by the <specGrp> referenced should be inserted at this point." href="ref-specGrpRef.html">specGrpRef</a> elements). The use of <a class="gi" title="(specification group) contains any convenient grouping of specifications for use within the current module." href="ref-specGrp.html">specGrp</a> and <a class="gi" title="(reference to a specification group) indicates that the declarations contained by the <specGrp> referenced should be inserted at this point." href="ref-specGrpRef.html">specGrpRef</a> permits the ODD markup to occur at the points in documentation where they are discussed, rather than all inside <a class="gi" title="(schema specification) generates a TEI-conformant schema and documentation for it." href="ref-schemaSpec.html">schemaSpec</a>. The <span class="att">target</span> attribute of any <a class="gi" title="(reference to a specification group) indicates that the declarations contained by the <specGrp> referenced should be inserted at this point." href="ref-specGrpRef.html">specGrpRef</a> should be followed, and the <a class="gi" title="(element specification) documents the structure, content, and purpose of a single element type." href="ref-elementSpec.html">elementSpec</a>, <a class="gi" title="(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." href="ref-classSpec.html">classSpec</a>, and <a class="gi" title="(macro specification) documents the function and implementation of a pattern." href="ref-macroSpec.html">macroSpec</a>, elements in the corresponding <a class="gi" title="(specification group) contains any convenient grouping of specifications for use within the current module." href="ref-specGrp.html">specGrp</a> should be processed as described in the previous item; <a class="gi" title="(reference to a specification group) indicates that the declarations contained by the <specGrp> referenced should be inserted at this point." href="ref-specGrpRef.html">specGrpRef</a> elements should be processed as described here.</dd><dt><span>references to TEI Modules</span></dt><dd><a class="gi" title="(module reference) references a module which is to be incorporated into a schema." href="ref-moduleRef.html">moduleRef</a> elements with <span class="att">key</span> attributes refer to components of the TEI. The value of the <span class="att">key</span> attribute matches the <span class="att">ident</span> attribute of the <a class="gi" title="(module specification) documents the structure, content, and purpose of a single module, i.e. a named and externally visible group of declarations." href="ref-moduleSpec.html">moduleSpec</a> element defining a TEI module. The <span class="att">key</span> must be dereferenced by some means, such as reading an XML file with the TEI ODD specification (either from the local hard drive or off the Web), or looking up the reference in an XML database (again, locally or remotely); whatever means is used, it should return a stream of XML containing the element, class, and macro specifications collected together in the specified module. These specification elements are then processed in the same way as if they had been supplied directly within the <a class="gi" title="(schema specification) generates a TEI-conformant schema and documentation for it." href="ref-schemaSpec.html">schemaSpec</a> being processed.</dd><dt><span>references to external modules</span></dt><dd>a <a class="gi" title="(module reference) references a module which is to be incorporated into a schema." href="ref-moduleRef.html">moduleRef</a> element may also refer to a compatible external module by means of its <span class="att">url</span> attribute; the content of such modules, which must be available in the RELAX NG XML syntax, are passed directly and without modification to the output schema when that is created.</dd></dl><p>Each object obtained from the TEI ODD specification using <a class="gi" title="(module reference) references a module which is to be incorporated into a schema." href="ref-moduleRef.html">moduleRef</a> by means of the <span class="att">key</span> attribute must be checked against objects in the customization <a class="gi" title="(schema specification) generates a TEI-conformant schema and documentation for it." href="ref-schemaSpec.html">schemaSpec</a> according to the following rules: </p><ol class="numbered"><li class="item">if there is an object in the ODD customization with the same value for the <span class="att">ident</span> attribute, and a <span class="att">mode</span> value of <span class="val">delete</span>, then the object from the module is ignored;</li><li class="item">if there is an object in the ODD customization with the same value for the <span class="att">ident</span> attribute, and a <span class="att">mode</span> value of <span class="val">replace</span>, then the object from the module is ignored, and the one from the ODD customization is used in its place;</li><li class="item">if there is an object in the ODD customization with the same value for the <span class="att">ident</span> attribute, and a <span class="att">mode</span> value of <span class="val">change</span>, then the two objects must be merged, as described below;</li><li class="item">if there is an object in the ODD customization with the same value for the <span class="att">ident</span> attribute, and a <span class="att">mode</span> value of <span class="val">add</span>, then an error condition should be raised;</li><li class="item">otherwise, the object from the module is copied to the result.</li></ol><p>To merge two objects with the same <span class="att">ident</span>, their component attributes and child elements must be looked at recursively. Each component may fall into one of the following four categories: </p><ol class="numbered"><li class="item">Some components may occur only once within the merged object (for example attributes, and <a class="gi" title="(alternate identifier) supplies the recommended XML name for an element, class, attribute, etc. in some language." href="ref-altIdent.html">altIdent</a>, <a class="gi" title="(content model) contains the text of a declaration for the schema documented." href="ref-content.html">content</a>, or <a class="gi" title="specifies all the classes of which the documented element or class is a member or subclass." href="ref-classes.html">classes</a> elements). If such a component is found in the ODD customization, it will be copied to the output; if it is not found there, but is present in the TEI ODD specification, then that will be copied to the output.</li><li class="item">Some components are grouping objects (<a class="gi" title="contains documentation for all the attributes associated with this element, as a series of <attDef> elements." href="ref-attList.html">attList</a>, <a class="gi" title="(value list) contains one or more <valItem> elements defining possible values." href="ref-valList.html">valList</a>, for example); these are always copied to the output, and their children are then processed following the rules given in this list.</li><li class="item">Some components are ‘identifiable’: this means that they are members of the <a class="link_odd" title="provides the identifying attribute for elements which can be subsequently referenced by means of a @key attribute." href="ref-att.identified.html">att.identified</a> class from which they inherit the <span class="att">ident</span> attribute; examples include <a class="gi" title="(attribute definition) contains the definition of a single attribute." href="ref-attDef.html">attDef</a> and <a class="gi" title="documents a single value in a predefined list of values." href="ref-valItem.html">valItem</a>. A component of this type will be processed according to its <span class="att">mode</span> attribute, following the rules given above.</li><li class="item">Some components may occur multiple times, but are neither grouped nor identifiable. Examples include the members of <a class="link_odd" title="groups elements which provide an alternative name, explanation, or description for any markup construct." href="ref-model.glossLike.html">model.glossLike</a> such as <a class="gi" title="(equivalent) specifies a component which is considered equivalent to the parent element, either by co-reference, or by external link." href="ref-equiv.html">equiv</a>, <a class="gi" title="(description) contains a brief description of the object documented by its parent element, typically a documentation element or an entity." href="ref-desc.html">desc</a>, <a class="gi" title="identifies a phrase or word used to provide a gloss or definition for some other word or phrase." href="ref-gloss.html">gloss</a>, the <a class="gi" title="groups an example demonstrating the use of an element along with optional paragraphs of commentary." href="ref-exemplum.html">exemplum</a>, <a class="gi" title="contains any commentary or discussion about the usage of an element, attribute, class, or entity not otherwise documented within the containing element." href="ref-remarks.html">remarks</a>, <a class="gi" title="(list of references) supplies a list of significant references to places where this element is discussed, in the current document or elsewhere." href="ref-listRef.html">listRef</a>, <a class="gi" title="specifies the declared value for an attribute, by referring to any datatype defined by the chosen schema language." href="ref-datatype.html">datatype</a> or <a class="gi" title="(default value) specifies the default declared value for an attribute." href="ref-defaultVal.html">defaultVal</a> elements. These should be copied from both the TEI ODD specification and the ODD customization, and all occurrences included in the output.</li></ol><div class="p">A special problem arises with elements which are members of attribute classes, as they are permitted to override attributes inherited from a class. For example, consider this simple modification: <div id="index-egXML-d52e152107" class="pre egXML_valid"><span class="element"><elementSpec <span class="attribute">ident</span>="<span class="attributevalue">p</span>"></span><br /> <span class="element"><classes></span><br /> <span class="element"><memberOf <span class="attribute">key</span>="<span class="attributevalue">att.typed</span>"/></span><br /> <span class="element"></classes></span><br /> <span class="element"><content></span><br /><span class="comment"><!--…--></span><br /> <span class="element"></content></span><br /><span class="element"></elementSpec></span></div> The effect of its membership in the <a class="link_odd" title="provides attributes which can be used to classify or subclassify elements in any way." href="ref-att.typed.html">att.typed</a> class is to provide <a class="gi" title="(paragraph) marks paragraphs in prose." href="ref-p.html">p</a> with a <span class="att">type</span> attribute and a <span class="att">subtype</span> attribute. If we wish <a class="gi" title="(paragraph) marks paragraphs in prose." href="ref-p.html">p</a> to <em>not</em> have <span class="att">subtype</span>, we could extend the customization in our schema as follows: <div id="index-egXML-d52e152136" class="pre egXML_valid"><span class="element"><elementSpec <span class="attribute">ident</span>="<span class="attributevalue">p</span>"></span><br /> <span class="element"><classes></span><br /> <span class="element"><memberOf <span class="attribute">key</span>="<span class="attributevalue">att.typed</span>"/></span><br /> <span class="element"></classes></span><br /> <span class="element"><content></span><br /><span class="comment"><!--… --></span><br /> <span class="element"></content></span><br /> <span class="element"><attList></span><br /> <span class="element"><attDef <span class="attribute">ident</span>="<span class="attributevalue">subtype</span>" <span class="attribute">mode</span>="<span class="attributevalue">delete</span>"/></span><br /> <span class="element"></attList></span><br /><span class="element"></elementSpec></span></div> This means that when <span class="tag"><memberOf key="att.typed"/></span> is processed, that class is looked up, each attribute which it defines is examined in turn, and the customization is searched for an override. If the modification is of the attribute class itself, work proceeds as usual; if, however, the modification is at the element level, the class reference is deleted and a series of <a class="gi" title="(attribute pointer) points to the definition of an attribute or group of attributes." href="ref-attRef.html">attRef</a> elements is added to the element, one for each attribute inherited from the class. Since attribute classes can themselves be members of other attribute classes, membership must be followed recursively.</div><div class="p">The effect of the concatenation of unidentifiable components should be considered carefully. An original may have <div id="index-egXML-d52e152153" class="pre egXML_valid"><span class="element"><elementSpec <span class="attribute">ident</span>="<span class="attributevalue">p</span>"></span><br /> <span class="element"><desc></span>marks paragraphs in prose.<span class="element"></desc></span><br /><span class="comment"><!--…--></span><br /><span class="element"></elementSpec></span></div> which would usefully be extended with this: <div id="index-egXML-d52e152159" class="pre egXML_valid"><span class="element"><elementSpec <span class="attribute">ident</span>="<span class="attributevalue">p</span>" <span class="attribute">mode</span>="<span class="attributevalue">change</span>"></span><br /> <span class="element"><desc <span class="attribute">xml:lang</span>="<span class="attributevalue">es</span>"></span>marca párrafos en prosa.<span class="element"></desc></span><br /><span class="comment"><!--…--></span><br /><span class="element"></elementSpec></span></div> to provide an alternate description in another language. Nothing prevents the user from supplying <a class="gi" title="(description) contains a brief description of the object documented by its parent element, typically a documentation element or an entity." href="ref-desc.html">desc</a> several times in the same language, and subsequent applications will have to decide what that may mean.</div><p>Similar considerations apply to multiple example elements, though these are less likely to cause problems in documentation. Note that existing examples can only be deleted by supplying a completely new <a class="gi" title="(element specification) documents the structure, content, and purpose of a single element type." href="ref-elementSpec.html">elementSpec</a> in <span class="val">replace</span> mode, since the <a class="gi" title="groups an example demonstrating the use of an element along with optional paragraphs of commentary." href="ref-exemplum.html">exemplum</a> element is not identifiable.</p><div class="p">In the processing of the content models of elements and the content of macros, deleted elements may require special attention.<span id="Note132_return"><a class="notelink" title="The carthago program behind the Pizza Chef application, written by Michael Sperberg-McQueen for TEI P3 and P4, went to very great efforts to get this …" href="#Note132"><sup>95</sup></a></span> A content model like this: <div id="index-egXML-d52e152186" class="pre egXML_valid"><span class="element"><elementSpec <span class="attribute">ident</span>="<span class="attributevalue">person</span>"></span><br /><span class="comment"><!-- ... --></span><br /> <span class="element"><content></span><br /> <span class="element"><alternate></span><br /> <span class="element"><classRef <span class="attribute">key</span>="<span class="attributevalue">model.pLike</span>"<br /> <span class="attribute">minOccurs</span>="<span class="attributevalue">1</span>" <span class="attribute">maxOccurs</span>="<span class="attributevalue">unbounded</span>"/></span><br /> <span class="element"><alternate <span class="attribute">minOccurs</span>="<span class="attributevalue">0</span>"<br /> <span class="attribute">maxOccurs</span>="<span class="attributevalue">unbounded</span>"></span><br /> <span class="element"><classRef <span class="attribute">key</span>="<span class="attributevalue">model.personPart</span>"/></span><br /> <span class="element"><classRef <span class="attribute">key</span>="<span class="attributevalue">model.global</span>"/></span><br /> <span class="element"></alternate></span><br /> <span class="element"></alternate></span><br /> <span class="element"></content></span><br /><span class="comment"><!-- ... --></span><br /><span class="element"></elementSpec></span></div> requires no special treatment because everything is expressed in terms of model classes; if the class <a class="link_odd" title="groups elements which form part of the description of a person." href="ref-model.personPart.html">model.personPart</a> is deleted explicitly, or removed because all of its members have been deleted, then <a class="link_odd" title="groups elements which may appear at any point within a TEI text." href="ref-model.global.html">model.global</a> is left as the only child of the inner <a class="gi" title="an alternation of references" href="ref-alternate.html">alternate</a>. An ODD processor may or may not elect to simplify the resulting choice between nothing and <a class="link_odd" title="groups elements which may appear at any point within a TEI text." href="ref-model.global.html">model.global</a> by removing the wrapper <a class="gi" title="an alternation of references" href="ref-alternate.html">alternate</a> element. However, such simplification may be considerably more complex in the general case and an ODD processor is therefore likely to be more successful in carrying out such simplification as a distinct stage during processing of ODD sources.</div><div class="p">If an element refers directly to an element child, like this: <div id="index-egXML-d52e152217" class="pre egXML_valid"><span class="element"><elementSpec <span class="attribute">ident</span>="<span class="attributevalue">figure</span>"></span><br /><span class="comment"><!--…--></span><br /> <span class="element"><content></span><br /> <span class="element"><alternate <span class="attribute">minOccurs</span>="<span class="attributevalue">0</span>"<br /> <span class="attribute">maxOccurs</span>="<span class="attributevalue">unbounded</span>"></span><br /> <span class="element"><classRef <span class="attribute">key</span>="<span class="attributevalue">model.pLike</span>"/></span><br /> <span class="element"><classRef <span class="attribute">key</span>="<span class="attributevalue">model.global</span>"/></span><br /> <span class="element"><elementRef <span class="attribute">key</span>="<span class="attributevalue">figure</span>"/></span><br /> <span class="element"><elementRef <span class="attribute">key</span>="<span class="attributevalue">figDesc</span>"/></span><br /> <span class="element"><classRef <span class="attribute">key</span>="<span class="attributevalue">model.graphicLike</span>"/></span><br /> <span class="element"><classRef <span class="attribute">key</span>="<span class="attributevalue">model.headLike</span>"/></span><br /> <span class="element"></alternate></span><br /> <span class="element"></content></span><br /><span class="comment"><!--…--></span><br /><span class="element"></elementSpec></span></div> and <a class="gi" title="(description of figure) contains a brief prose description of the appearance or content of a graphic figure, for use when documenting an image without displaying it." href="ref-figDesc.html">figDesc</a> has been deleted,<span id="Note133_return"><a class="notelink" title="Note that deletion of required elements will cause the schema specification to accept as valid documents which cannot be TEI-conformant, since they no…" href="#Note133"><sup>96</sup></a></span> it will be necessary to remove that reference, or the resulting schema will be invalid.</div><p>The result of the work carried out should be a new <a class="gi" title="(schema specification) generates a TEI-conformant schema and documentation for it." href="ref-schemaSpec.html">schemaSpec</a> which contains a complete and internally consistent set of element, class, and macro specifications, possibly also including <a class="gi" title="(module reference) references a module which is to be incorporated into a schema." href="ref-moduleRef.html">moduleRef</a> elements with <span class="att">url</span> attributes identifying external modules.</p></div><div class="teidiv2" id="IMGS"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#IM-unified"><span class="headingNumber">23.5.1 </span>Making a Unified ODD</a></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#IM-naming"><span class="headingNumber">23.5.3 </span>Names and Documentation in Generated Schemas</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h4><span class="bookmarklink"><a class="bookmarklink" href="#IMGS" title="link to this section "><span class="invisible">TEI: Generating Schemas</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.5.2 </span><span class="head">Generating Schemas</span></h4><p>Assuming that any modifications have been resolved, as outlined in the previous section, making a schema is now a four stage process: </p><ol class="numbered"><li class="item">all datatype and other macro specifications must be collected together and declared at the start of the output schema;</li><li class="item">all classes must be declared in the right order (order is significant because since some classes reference others);</li><li class="item">all elements are declared;</li><li class="item">any <a class="gi" title="(module reference) references a module which is to be incorporated into a schema." href="ref-moduleRef.html">moduleRef</a> elements with a <span class="att">url</span> attribute identifying an external schema must be processed.</li></ol><p> Working in this order gives the best chance of successfully supporting all the schema languages. However, there are a number of obstacles to overcome along the way.</p><p>An ODD processor may choose to use any desired schema language or languages for its schema output, since ODD specifications are expressed as far as possible in a form independent of any schema language. The current TEI ODD processing system produces schema output in the three main schema languages as follows: </p><ul class="bulleted"><li class="item">A RELAX NG (XML) schema is generated by converting content models, datatypes, and macro specifications provided within the ODD specification; a version re-expressed in the RELAX NG compact syntax is generated using James Clark's <span class="name">trang</span> application.</li><li class="item">A DTD schema is generated by converting the RELAX NG content models to DTD language, often simplifying it to allow for the less-sophisticated output language.</li><li class="item">A W3C Schema schema is created by generating a RELAX NG schema and then using James Clark's <span class="name">trang</span> application.</li></ul><p> Note that the method used to generate W3C Schema means that a processor must ensure that the RELAX NG it generates follows the subset which <span class="name">trang</span> is able to translate properly (see further below)—this may involve simple trial and error.</p><p>Other projects may decide to follow a different route, perhaps implementing a direct ODD to W3C Schema translator.</p><p>Secondly, it is possible to create two rather different styles of schema. On the one hand, the schema can try to maintain all the flexibility of ODD by using the facilities of the schema language for parameterization; on the other, it can remove all customization features and produce a flat result which is not suitable for further manipulation. The TEI project currently generates both styles of schema; the first as a set of schema fragments in DTD and RELAX NG languages, which can be included as modules in other schemas, and customized further; the second as the output from a processor such as Roma, in which many of the parameterization features have been removed.</p><div class="p">The difference between the schema styles may be illustrated by considering this ODD specification: <div id="index-egXML-d52e152298" class="pre egXML_valid"><span class="element"><elementSpec <span class="attribute">module</span>="<span class="attributevalue">drama</span>"<br /> <span class="attribute">ident</span>="<span class="attributevalue">performance</span>"></span><br /><span class="comment"><!-- ... --></span><br /> <span class="element"><classes></span><br /> <span class="element"><memberOf <span class="attribute">key</span>="<span class="attributevalue">model.frontPart.drama</span>"/></span><br /> <span class="element"></classes></span><br /> <span class="element"><content></span><br /> <span class="element"><sequence></span><br /> <span class="element"><alternate <span class="attribute">minOccurs</span>="<span class="attributevalue">0</span>"<br /> <span class="attribute">maxOccurs</span>="<span class="attributevalue">unbounded</span>"></span><br /> <span class="element"><classRef <span class="attribute">key</span>="<span class="attributevalue">model.divTop</span>"/></span><br /> <span class="element"><classRef <span class="attribute">key</span>="<span class="attributevalue">model.global</span>"/></span><br /> <span class="element"></alternate></span><br /> <span class="element"><sequence <span class="attribute">minOccurs</span>="<span class="attributevalue">1</span>"<br /> <span class="attribute">maxOccurs</span>="<span class="attributevalue">unbounded</span>"></span><br /> <span class="element"><classRef <span class="attribute">key</span>="<span class="attributevalue">model.common</span>"/></span><br /> <span class="element"><classRef <span class="attribute">key</span>="<span class="attributevalue">model.global</span>"<br /> <span class="attribute">minOccurs</span>="<span class="attributevalue">0</span>" <span class="attribute">maxOccurs</span>="<span class="attributevalue">unbounded</span>"/></span><br /> <span class="element"></sequence></span><br /> <span class="element"><sequence <span class="attribute">minOccurs</span>="<span class="attributevalue">0</span>"<br /> <span class="attribute">maxOccurs</span>="<span class="attributevalue">unbounded</span>"></span><br /> <span class="element"><classRef <span class="attribute">key</span>="<span class="attributevalue">model.divBottom</span>"/></span><br /> <span class="element"><classRef <span class="attribute">key</span>="<span class="attributevalue">model.global</span>"<br /> <span class="attribute">minOccurs</span>="<span class="attributevalue">0</span>" <span class="attribute">maxOccurs</span>="<span class="attributevalue">unbounded</span>"/></span><br /> <span class="element"></sequence></span><br /> <span class="element"></sequence></span><br /> <span class="element"></content></span><br /><span class="comment"><!-- ... --></span><br /><span class="element"></elementSpec></span></div> A simple rendering to RELAX NG produces this: <pre class="pre_eg cdata">
performance =
element performance {
(model.divTop | model.global)*,
(model.common, model.global*)+,
(model.divBottom, model.global*)*
att.global.attribute.xmlspace,
att.global.attribute.xmlid,
att.global.attribute.n,
att.global.attribute.xmllang,
att.global.attribute.rend,
att.global.attribute.xmlbase,
att.global.linking.attribute.corresp,
att.global.linking.attribute.synch,
att.global.linking.attribute.sameAs,
att.global.linking.attribute.copyOf,
att.global.linking.attribute.next,
att.global.linking.attribute.prev,
att.global.linking.attribute.exclude,
att.global.linking.attribute.select
}
</pre> In the above, a subsequent redefinition of the attribute class (such as <a class="link_odd" title="provides attributes common to all elements in the TEI encoding scheme." href="ref-att.global.html">att.global</a>) would have no effect, since references to such classes have been expanded to reference their constituent attributes.</div><p>The equivalent parameterized version might look like this: </p><pre class="pre_eg cdata">
performance =
element performance { performance.content, performance.attributes }
performance.content =
(model.divTop | model.global)*,
(model.common, model.global*)+,
(model.divBottom, model.global*)*
performance.attributes = att.global.attributes, empty
</pre><p> Here, the attribute class <a class="link_odd" title="provides attributes common to all elements in the TEI encoding scheme." href="ref-att.global.html">att.global</a> is provided via an explicit reference (<code>att.global.attributes</code>), and can therefore be redefined. Moreover, the attributes are separated from the content model, allowing either to be overridden.</p><p>In the remainder of these section, the terms <span class="term">simple schema</span> and <span class="term">parameterized schema</span> are used to distinguish the two schema types. An ODD processor is not required to support both, though the simple schema output is generally preferable for most applications.</p><div class="p">Thirdly, the problem of missing components must be resolved. For example, consider this (fictitious) model for <a class="gi" title="(speech) contains an individual speech in a performance text, or a passage presented as such in a prose or verse text." href="ref-sp.html">sp</a>: <div id="index-egXML-d52e152346" class="pre egXML_valid"><span class="element"><elementSpec <span class="attribute">ident</span>="<span class="attributevalue">sp</span>"></span><br /><span class="comment"><!--…--></span><br /> <span class="element"><content></span><br /> <span class="element"><classRef <span class="attribute">key</span>="<span class="attributevalue">model.global</span>"<br /> <span class="attribute">minOccurs</span>="<span class="attributevalue">0</span>" <span class="attribute">maxOccurs</span>="<span class="attributevalue">unbounded</span>"/></span><br /> <span class="element"><sequence <span class="attribute">minOccurs</span>="<span class="attributevalue">0</span>" <span class="attribute">maxOccurs</span>="<span class="attributevalue">1</span>"></span><br /> <span class="element"><elementRef <span class="attribute">key</span>="<span class="attributevalue">speaker</span>"/></span><br /> <span class="element"><classRef <span class="attribute">key</span>="<span class="attributevalue">model.global</span>"<br /> <span class="attribute">minOccurs</span>="<span class="attributevalue">0</span>" <span class="attribute">maxOccurs</span>="<span class="attributevalue">unbounded</span>"/></span><br /> <span class="element"></sequence></span><br /> <span class="element"></content></span><br /><span class="comment"><!--…--></span><br /><span class="element"></elementSpec></span></div> This proposes anything from the class <a class="link_odd" title="groups elements which may appear at any point within a TEI text." href="ref-model.global.html">model.global</a>, followed optionally by a <a class="gi" title="() contains a specialized form of heading or label, giving the name of one or more speakers in a dramatic text or fragment." href="ref-speaker.html">speaker</a> element followed by anything from the <a class="link_odd" title="groups elements which may appear at any point within a TEI text." href="ref-model.global.html">model.global</a> class. What happens if <a class="gi" title="() contains a specialized form of heading or label, giving the name of one or more speakers in a dramatic text or fragment." href="ref-speaker.html">speaker</a> is removed from the schema? The following would result: <div id="index-egXML-d52e152369" class="pre egXML_invalid"><span class="element"><elementSpec <span class="attribute">ident</span>="<span class="attributevalue">sp</span>"></span><br /><span class="comment"><!--…--></span><br /> <span class="element"><content></span><br /> <span class="element"><classRef <span class="attribute">key</span>="<span class="attributevalue">model.global</span>"<br /> <span class="attribute">minOccurs</span>="<span class="attributevalue">0</span>" <span class="attribute">maxOccurs</span>="<span class="attributevalue">unbounded</span>"/></span><br /> <span class="element"><classRef <span class="attribute">key</span>="<span class="attributevalue">model.global</span>"<br /> <span class="attribute">minOccurs</span>="<span class="attributevalue">0</span>" <span class="attribute">maxOccurs</span>="<span class="attributevalue">unbounded</span>"/></span><br /> <span class="element"></content></span><br /><span class="comment"><!--…--></span><br /><span class="element"></elementSpec></span></div> which is illegal in DTD and W3C schema languages, since for a given member of <a class="link_odd" title="groups elements which may appear at any point within a TEI text." href="ref-model.global.html">model.global</a> it is impossible to be sure which rule is being used. This situation is not detected when RELAX NG is used, since the language is able to cope with non-deterministic content models of this kind and does not require that only a single rule be used.</div><p>Finally, an application will need to have some method of associating the schema with document instances that use it. The TEI does not mandate any particular method of doing this, since different schema languages and processors vary considerably in their requirements. ODD processors may wish to build in support for some of the methods for associating a document instance with a schema. The TEI does not mandate any particular method, but does suggest that those which are already part of XML (the DOCTYPE declaration for DTDs) and W3C Schema (the <span class="att">xsi:schemaLocation</span> attribute) be supported where possible.</p><p>In order for the <span class="att">xsi:schemaLocation</span> attribute to be valid when a document is validated against either a DTD or a RELAX NG schema, ODD processors may wish to add declarations for this attribute and its namespace to the root element, even though these are not part of the TEI <span class="foreign">per se</span>. For DTDs this means adding </p><pre class="pre_eg cdata">xsi:schemaLocation CDATA #IMPLIED xmlns:xsi CDATA #FIXED 'http://www.w3.org/2001/XMLSchema-instance'</pre><p> to the list of attributes on the root element, which permits the non-namespace-aware DTD language to recognize the <code>xsi:schemaLocation</code> notation. For RELAX NG, the namespace and attribute would be declared in the usual way: </p><pre class="pre_eg cdata">namespace xsi = "http://www.w3.org/2001/XMLSchema-instance"</pre><p> and </p><pre class="pre_eg cdata">attribute xsi:schemaLocation { list { data.namespace, data.pointer }+ }</pre><p> inside the root element declaration.</p><p>Note that declaration of the <span class="att">xsi:schemaLocation</span> attribute in a W3C Schema schema is not permitted. Therefore, if W3C Schemas are being generated by converting the RELAX NG schema (for example, with <span class="name">trang</span>), it may be necessary to perform that conversion prior to adding the <span class="att">xsi:schemaLocation</span> declaration to the RELAX NG.</p><p>It is recognized that this is an unsatisfactory solution, but it permits users to take advantage of the W3C Schema facility for indicating a schema, while still permitting documents to be validated using DTD and RELAX NG processors without any conflict.</p></div><div class="teidiv2" id="IM-naming"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#IMGS"><span class="headingNumber">23.5.2 </span>Generating Schemas</a></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#IMRN"><span class="headingNumber">23.5.4 </span>Making a RELAX NG Schema</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h4><span class="bookmarklink"><a class="bookmarklink" href="#IM-naming" title="link to this section "><span class="invisible">TEI: Names and Documentation in Generated Schemas</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.5.3 </span><span class="head">Names and Documentation in Generated Schemas</span></h4><p>When processing class, element, or macro specifications, there are three general rules: </p><ol class="numbered"><li class="item">If a RELAX NG pattern or DTD parameter entity is being created, its name is the value of the corresponding <span class="att">ident</span> attribute, prefixed by the value of any <span class="att">prefix</span> attribute on <a class="gi" title="(schema specification) generates a TEI-conformant schema and documentation for it." href="ref-schemaSpec.html">schemaSpec</a>. This allows for elements from an external schema to be mixed in without risk of name clashes, since all TEI elements can be given a distinctive prefix such as <span class="val">tei_</span>. Thus <div id="index-egXML-d52e152441" class="pre egXML_valid"><span class="element"><schemaSpec <span class="attribute">ident</span>="<span class="attributevalue">test</span>" <span class="attribute">prefix</span>="<span class="attributevalue">tei_</span>"></span><br /> <span class="element"><elementSpec <span class="attribute">ident</span>="<span class="attributevalue">sp</span>"></span><br /><span class="comment"><!--...--></span><br /> <span class="element"></elementSpec></span><br /><span class="element"></schemaSpec></span></div> may generate a RELAX NG (compact syntax) pattern like this: <pre class="pre_eg cdata">tei_sp = element sp { ... } </pre> References to these patterns (or, in DTDs, parameter entities) also need to be prefixed with the same value.</li><li class="item">If an element or attribute is being created, its default name is the value of the <span class="att">ident</span> attribute, but if there is an <a class="gi" title="(alternate identifier) supplies the recommended XML name for an element, class, attribute, etc. in some language." href="ref-altIdent.html">altIdent</a> child, its content is used instead.</li><li class="item">Where appropriate, the documentation strings in <a class="gi" title="identifies a phrase or word used to provide a gloss or definition for some other word or phrase." href="ref-gloss.html">gloss</a> and <a class="gi" title="(description) contains a brief description of the object documented by its parent element, typically a documentation element or an entity." href="ref-desc.html">desc</a> should be copied into the generated schema. If there is only one occurrence of either of these elements, it should be used regardless, but if there are several, local processing rules will need to be applied. For example, if there are several with different values of <span class="att">xml:lang</span>, a locale indication in the processing environment might be used to decide which to use. For example, <div id="index-egXML-d52e152469" class="pre egXML_valid"><span class="element"><elementSpec <span class="attribute">module</span>="<span class="attributevalue">core</span>" <span class="attribute">ident</span>="<span class="attributevalue">head</span>"></span><br /> <span class="element"><equiv/></span><br /> <span class="element"><gloss></span>heading<span class="element"></gloss></span><br /> <span class="element"><gloss <span class="attribute">xml:lang</span>="<span class="attributevalue">fr</span>"></span>en-tête<span class="element"></gloss></span><br /> <span class="element"><gloss <span class="attribute">xml:lang</span>="<span class="attributevalue">es</span>"></span>encabezamiento<span class="element"></gloss></span><br /> <span class="element"><gloss <span class="attribute">xml:lang</span>="<span class="attributevalue">it</span>"></span>titolo<span class="element"></gloss></span><br /><span class="comment"><!-- ... --></span><br /><span class="element"></elementSpec></span></div> might generate a RELAX NG schema fragment like the following, if the locale is determined to be French: <pre class="pre_eg cdata">
head =
## en-tête
element head { head.content, head.attributes }
</pre></li></ol><p> Alternatively, a selection might be made on the basis of the value of the <span class="att">version</span> attribute which these elements carry as members of the <a class="link_odd" title="provides attributes used to indicate the status of a translatable portion of an ODD document." href="ref-att.translatable.html">att.translatable</a> class.</p><p>In addition, there are three conventions about naming patterns relating to classes; ODD processors need not follow them, but those reading the schemas generated by the TEI project will find it necessary to understand them: </p><ol class="numbered"><li class="item">when a pattern for an attribute class is created, it is named after the attribute class identifier (as above) suffixed by <code>.attributes</code> (e.g. <code>att.editLike.attributes</code>);</li><li class="item">when a pattern for an attribute is created, it is named after the attribute class identifier (as above) suffixed by <code>.attribute.</code> and then the identifier of the attribute (e.g. <code>att.editLike.attribute.resp</code>);</li><li class="item">when a parameterized schema is created, each element generates patterns for its attributes and its contents separately, suffixing respectively <code>.attributes</code> and <code>.contents</code> to the element name.</li></ol></div><div class="teidiv2" id="IMRN"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#IM-naming"><span class="headingNumber">23.5.3 </span>Names and Documentation in Generated Schemas</a></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#IM-makeDTD"><span class="headingNumber">23.5.5 </span>Making a DTD</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h4><span class="bookmarklink"><a class="bookmarklink" href="#IMRN" title="link to this section "><span class="invisible">TEI: Making a RELAX NG Schema</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.5.4 </span><span class="head">Making a RELAX NG Schema</span></h4><p>To create a RELAX NG schema, the processor processes every <a class="gi" title="(macro specification) documents the function and implementation of a pattern." href="ref-macroSpec.html">macroSpec</a>, <a class="gi" title="(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." href="ref-classSpec.html">classSpec</a>, and <a class="gi" title="(element specification) documents the structure, content, and purpose of a single element type." href="ref-elementSpec.html">elementSpec</a> in turn, creating a RELAX NG pattern for each, using the naming conventions listed above. The order of declaration is not important, and a processor may well sort them into alphabetical order of identifier.</p><p>A complete RELAX NG schema must have an <span class="gi"><rng:start></span> element defining which elements can occur as the root of a document. The ODD <a class="gi" title="(schema specification) generates a TEI-conformant schema and documentation for it." href="ref-schemaSpec.html">schemaSpec</a> has an optional <span class="att">start</span> attribute, containing one or more patterns, which can be used to construct the <span class="gi"><rng:start></span>. A pattern normally corresponds to an element name, but if a prefix (see above, <a class="link_ptr" href="USE.html#IM-naming" title="Names and Documentation in Generated Schemas"><span class="headingNumber">23.5.3 </span>Names and Documentation in Generated Schemas</a>) is supplied for an element, the pattern consists of the prefix name with the element name.</p><div class="teidiv3" id="IMMA"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#IMCL"><span class="headingNumber">23.5.4.2 </span>Classes</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h5><span class="bookmarklink"><a class="bookmarklink" href="#IMMA" title="link to this section "><span class="invisible">TEI: Macros</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.5.4.1 </span><span class="head">Macros</span></h5><div class="p">An ODD macro generates a corresponding RELAX NG pattern by processing the body of the <a class="gi" title="(content model) contains the text of a declaration for the schema documented." href="ref-content.html">content</a> element in the same way as elsewhere. Thus <div id="index-egXML-d52e152559" class="pre egXML_valid"><span class="element"><macroSpec <span class="attribute">module</span>="<span class="attributevalue">tei</span>" <span class="attribute">type</span>="<span class="attributevalue">pe</span>"<br /> <span class="attribute">ident</span>="<span class="attributevalue">macro.phraseSeq</span>"></span><br /> <span class="element"><content></span><br /> <span class="element"><alternate <span class="attribute">minOccurs</span>="<span class="attributevalue">0</span>"<br /> <span class="attribute">maxOccurs</span>="<span class="attributevalue">unbounded</span>"></span><br /> <span class="element"><textNode/></span><br /> <span class="element"><classRef <span class="attribute">key</span>="<span class="attributevalue">model.gLike</span>"/></span><br /> <span class="element"><classRef <span class="attribute">key</span>="<span class="attributevalue">model.phrase</span>"/></span><br /> <span class="element"><classRef <span class="attribute">key</span>="<span class="attributevalue">model.global</span>"/></span><br /> <span class="element"></alternate></span><br /> <span class="element"></content></span><br /><span class="element"></macroSpec></span></div> produces the following <div id="index-egXML-d52e152568" class="pre egXML_valid"><span class="element"><rng:define <span class="attribute">name</span>="<span class="attributevalue">macro.phraseSeq</span>"></span><br /> <span class="element"><rng:zeroOrMore></span><br /> <span class="element"><rng:choice></span><br /> <span class="element"><rng:text/></span><br /> <span class="element"><rng:ref <span class="attribute">name</span>="<span class="attributevalue">model.gLike</span>"/></span><br /> <span class="element"><rng:ref <span class="attribute">name</span>="<span class="attributevalue">model.phrase</span>"/></span><br /> <span class="element"><rng:ref <span class="attribute">name</span>="<span class="attributevalue">model.global</span>"/></span><br /> <span class="element"></rng:choice></span><br /> <span class="element"></rng:zeroOrMore></span><br /><span class="element"></rng:define></span></div> </div></div><div class="teidiv3" id="IMCL"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#IMMA"><span class="headingNumber">23.5.4.1 </span>Macros</a></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#IMEL"><span class="headingNumber">23.5.4.3 </span>Elements</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h5><span class="bookmarklink"><a class="bookmarklink" href="#IMCL" title="link to this section "><span class="invisible">TEI: Classes</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.5.4.2 </span><span class="head">Classes</span></h5><div class="p">An ODD model class always generates a RELAX NG pattern definition listing all the members of the class in alternation. For example <div id="index-egXML-d52e152583" class="pre egXML_valid"><span class="element"><classSpec <span class="attribute">module</span>="<span class="attributevalue">tei</span>" <span class="attribute">type</span>="<span class="attributevalue">model</span>"<br /> <span class="attribute">ident</span>="<span class="attributevalue">model.measureLike</span>"></span><br /><span class="comment"><!-- ... --></span><br /><span class="element"></classSpec></span></div> will produce something like the following: <div id="index-egXML-d52e152587" class="pre egXML_valid"><span class="element"><rng:define <span class="attribute">name</span>="<span class="attributevalue">model.measureLike</span>"></span><br /> <span class="element"><rng:choice></span><br /> <span class="element"><rng:ref <span class="attribute">name</span>="<span class="attributevalue">num</span>"/></span><br /> <span class="element"><rng:ref <span class="attribute">name</span>="<span class="attributevalue">measure</span>"/></span><br /> <span class="element"><rng:ref <span class="attribute">name</span>="<span class="attributevalue">measureGrp</span>"/></span><br /> <span class="element"></rng:choice></span><br /><span class="element"></rng:define></span></div> assuming that the elements <a class="gi" title="(number) contains a number, written in any form." href="ref-num.html">num</a>, <a class="gi" title="contains a word or phrase referring to some quantity of an object or commodity, usually comprising a number, a unit, and a commodity name." href="ref-measure.html">measure</a>, and <a class="gi" title="(measure group) contains a group of dimensional specifications which relate to the same object, for example the height and width of a manuscript page." href="ref-measureGrp.html">measureGrp</a> are all defined in the schema concerned as members of that class. A model declaration may also generate a number of other patterns corresponding with sequences or alternations of the class members: <div id="index-egXML-d52e152606" class="pre egXML_valid"><span class="element"><rng:define <span class="attribute">name</span>="<span class="attributevalue">model.measureLike_sequence</span>"></span><br /> <span class="element"><rng:ref <span class="attribute">name</span>="<span class="attributevalue">num</span>"/></span><br /> <span class="element"><rng:ref <span class="attribute">name</span>="<span class="attributevalue">measure</span>"/></span><br /> <span class="element"><rng:ref <span class="attribute">name</span>="<span class="attributevalue">measureGrp</span>"/></span><br /><span class="element"></rng:define></span><br /><span class="element"><rng:define <span class="attribute">name</span>="<span class="attributevalue">model.measureLike_sequenceOptional</span>"></span><br /> <span class="element"><rng:optional></span><br /> <span class="element"><rng:ref <span class="attribute">name</span>="<span class="attributevalue">num</span>"/></span><br /> <span class="element"></rng:optional></span><br /> <span class="element"><rng:optional></span><br /> <span class="element"><rng:ref <span class="attribute">name</span>="<span class="attributevalue">measure</span>"/></span><br /> <span class="element"></rng:optional></span><br /> <span class="element"><rng:optional></span><br /> <span class="element"><rng:ref <span class="attribute">name</span>="<span class="attributevalue">measureGrp</span>"/></span><br /> <span class="element"></rng:optional></span><br /><span class="element"></rng:define></span><br /><span class="element"><rng:define <span class="attribute">name</span>="<span class="attributevalue">model.measureLike_sequenceOptionalRepeatable</span>"></span><br /> <span class="element"><rng:zeroOrMore></span><br /> <span class="element"><rng:ref <span class="attribute">name</span>="<span class="attributevalue">num</span>"/></span><br /> <span class="element"></rng:zeroOrMore></span><br /> <span class="element"><rng:zeroOrMore></span><br /> <span class="element"><rng:ref <span class="attribute">name</span>="<span class="attributevalue">measure</span>"/></span><br /> <span class="element"></rng:zeroOrMore></span><br /> <span class="element"><rng:zeroOrMore></span><br /> <span class="element"><rng:ref <span class="attribute">name</span>="<span class="attributevalue">measureGrp</span>"/></span><br /> <span class="element"></rng:zeroOrMore></span><br /><span class="element"></rng:define></span><br /><span class="element"><rng:define <span class="attribute">name</span>="<span class="attributevalue">model.measureLike_sequenceRepeatable</span>"></span><br /> <span class="element"><rng:oneOrMore></span><br /> <span class="element"><rng:ref <span class="attribute">name</span>="<span class="attributevalue">num</span>"/></span><br /> <span class="element"></rng:oneOrMore></span><br /> <span class="element"><rng:oneOrMore></span><br /> <span class="element"><rng:ref <span class="attribute">name</span>="<span class="attributevalue">measure</span>"/></span><br /> <span class="element"></rng:oneOrMore></span><br /> <span class="element"><rng:oneOrMore></span><br /> <span class="element"><rng:ref <span class="attribute">name</span>="<span class="attributevalue">measureGrp</span>"/></span><br /> <span class="element"></rng:oneOrMore></span><br /><span class="element"></rng:define></span></div> where the pattern name is created by appending an underscore and the name of the generation type to the class name.</div><p>When classes are referenced using the <a class="gi" title="points to the specification for an attribute or model class which is to be included in a schema" href="ref-classRef.html">classRef</a> element, it is possible to indicate which of the available patterns is required by means of the <span class="att">expand</span> attribute.</p><div class="p">Attribute classes work by producing a pattern containing definitions of the appropriate attributes. So <div id="index-egXML-d52e152643" class="pre egXML_valid"><span class="element"><classSpec <span class="attribute">module</span>="<span class="attributevalue">verse</span>" <span class="attribute">type</span>="<span class="attributevalue">atts</span>"<br /> <span class="attribute">ident</span>="<span class="attributevalue">att.enjamb</span>"></span><br /> <span class="element"><attList></span><br /> <span class="element"><attDef <span class="attribute">ident</span>="<span class="attributevalue">enjamb</span>" <span class="attribute">usage</span>="<span class="attributevalue">opt</span>"></span><br /> <span class="element"><equiv/></span><br /> <span class="element"><desc></span>indicates whether the end of a verse line is marked by enjambement.<span class="element"></desc></span><br /> <span class="element"><datatype></span><br /> <span class="element"><dataRef <span class="attribute">key</span>="<span class="attributevalue">teidata.enumerated</span>"/></span><br /> <span class="element"></datatype></span><br /> <span class="element"><valList <span class="attribute">type</span>="<span class="attributevalue">open</span>"></span><br /> <span class="element"><valItem <span class="attribute">ident</span>="<span class="attributevalue">no</span>"></span><br /> <span class="element"><equiv/></span><br /> <span class="element"><desc></span>the line is end-stopped <span class="element"></desc></span><br /> <span class="element"></valItem></span><br /> <span class="element"><valItem <span class="attribute">ident</span>="<span class="attributevalue">yes</span>"></span><br /> <span class="element"><equiv/></span><br /> <span class="element"><desc></span>the line in question runs on into the next <span class="element"></desc></span><br /> <span class="element"></valItem></span><br /> <span class="element"><valItem <span class="attribute">ident</span>="<span class="attributevalue">weak</span>"></span><br /> <span class="element"><equiv/></span><br /> <span class="element"><desc></span>the line is weakly enjambed <span class="element"></desc></span><br /> <span class="element"></valItem></span><br /> <span class="element"><valItem <span class="attribute">ident</span>="<span class="attributevalue">strong</span>"></span><br /> <span class="element"><equiv/></span><br /> <span class="element"><desc></span>the line is strongly enjambed<span class="element"></desc></span><br /> <span class="element"></valItem></span><br /> <span class="element"></valList></span><br /> <span class="element"></attDef></span><br /> <span class="element"></attList></span><br /><span class="element"></classSpec></span></div> produces <div id="index-egXML-d52e152670" class="pre egXML_valid"><span class="element"><rng:define <span class="attribute">name</span>="<span class="attributevalue">att.enjamb.attributes</span>"></span><br /> <span class="element"><rng:ref <span class="attribute">name</span>="<span class="attributevalue">att.enjamb.attribute.enjamb</span>"/></span><br /> <span class="element"><rng:empty/></span><br /><span class="element"></rng:define></span><br /><span class="element"><rng:define <span class="attribute">name</span>="<span class="attributevalue">att.enjamb.attribute.enjamb</span>"></span><br /> <span class="element"><rng:optional></span><br /> <span class="element"><rng:attribute <span class="attribute">name</span>="<span class="attributevalue">enjamb</span>"></span><br /> <span class="element"><rng:ref <span class="attribute">name</span>="<span class="attributevalue">teidata.enumerated</span>"/></span><br /> <span class="element"></rng:attribute></span><br /> <span class="element"></rng:optional></span><br /><span class="element"></rng:define></span></div> Since the processor may have expanded the attribute classes already, separate patterns are generated for each attribute in the class as well as one for the class itself. This allows an element to refer directly to a member of a class. Notice that the <a class="gi" title="(description) contains a brief description of the object documented by its parent element, typically a documentation element or an entity." href="ref-desc.html">desc</a> element is used to add an <span class="gi"><a:documentation></span> element to the schema, which some editors use to provide help during composition. The <a class="gi" title="(description) contains a brief description of the object documented by its parent element, typically a documentation element or an entity." href="ref-desc.html">desc</a> elements in the <a class="gi" title="(value list) contains one or more <valItem> elements defining possible values." href="ref-valList.html">valList</a> are used to create the human-readable sentence <span class="quote">‘Sample values include: 1] no; 2] yes; 3] weak; 4] strong’</span> Naturally, this behaviour is not mandatory; and other ODD processors may create documentation in other ways, or ignore those parts of the ODD specifications when creating schemas.</div><div class="p">An individual attribute consists of an <span class="gi"><rng:attribute></span> with a <span class="att">name</span> attribute derived according to the naming rules described above (<a class="link_ptr" href="USE.html#IM-naming" title="Names and Documentation in Generated Schemas"><span class="headingNumber">23.5.3 </span>Names and Documentation in Generated Schemas</a>). In addition, the ODD model supports a <a class="gi" title="(default value) specifies the default declared value for an attribute." href="ref-defaultVal.html">defaultVal</a>, which is transformed to a <span class="att">defaultValue</span> attribute in the namespace <span class="ident-ns">http://relaxng.org/ns/compatibility/annotations/1.0</span> on the <span class="gi"><rng:attribute></span>. The body of the attribute is taken from the <a class="gi" title="specifies the declared value for an attribute, by referring to any datatype defined by the chosen schema language." href="ref-datatype.html">datatype</a> child, unless there is a supporting <a class="gi" title="(value list) contains one or more <valItem> elements defining possible values." href="ref-valList.html">valList</a> with a <span class="att">type</span> value of <span class="val">closed</span>. In that case an <span class="gi"><rng:choice></span> is created, listing the allowed values. Thus the following attribute definition <div id="index-egXML-d52e152736" class="pre egXML_valid"><span class="element"><attDef <span class="attribute">ident</span>="<span class="attributevalue">full</span>" <span class="attribute">usage</span>="<span class="attributevalue">opt</span>"></span><br /> <span class="element"><defaultVal></span>yes<span class="element"></defaultVal></span><br /> <span class="element"><valList <span class="attribute">type</span>="<span class="attributevalue">closed</span>"></span><br /> <span class="element"><valItem <span class="attribute">ident</span>="<span class="attributevalue">yes</span>"></span><br /> <span class="element"><desc></span>the name component is spelled out in full.<span class="element"></desc></span><br /> <span class="element"></valItem></span><br /> <span class="element"><valItem <span class="attribute">ident</span>="<span class="attributevalue">abb</span>"></span><br /> <span class="element"><gloss></span>abbreviated<span class="element"></gloss></span><br /> <span class="element"><desc></span>the name component is given in an abbreviated form.<span class="element"></desc></span><br /> <span class="element"></valItem></span><br /> <span class="element"><valItem <span class="attribute">ident</span>="<span class="attributevalue">init</span>"></span><br /> <span class="element"><gloss></span>initial letter<span class="element"></gloss></span><br /> <span class="element"><desc></span>the name component is indicated only by one initial.<span class="element"></desc></span><br /> <span class="element"></valItem></span><br /> <span class="element"></valList></span><br /><span class="element"></attDef></span></div> may generate this RELAX NG code: <div id="index-egXML-d52e152755" class="pre egXML_valid"><span class="element"><rng:define <span class="attribute">name</span>="<span class="attributevalue">att.full</span>"></span><br /> <span class="element"><rng:optional></span><br /> <span class="element"><rng:attribute <span class="attribute">name</span>="<span class="attributevalue">full</span>"<br /> <span class="attribute">a:defaultValue</span>="<span class="attributevalue">yes</span>"></span><br /> <span class="element"><rng:choice></span><br /> <span class="element"><rng:value></span>yes<span class="element"></rng:value></span><br /> <span class="element"><rng:value></span>abb<span class="element"></rng:value></span><br /> <span class="element"><rng:value></span>init<span class="element"></rng:value></span><br /> <span class="element"></rng:choice></span><br /> <span class="element"></rng:attribute></span><br /> <span class="element"></rng:optional></span><br /><span class="element"></rng:define></span></div> Note the use of the <span class="ident-ns">http://relaxng.org/ns/compatibility/annotations/1.0</span> namespace to provide default values and documentation.</div></div><div class="teidiv3" id="IMEL"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#IMCL"><span class="headingNumber">23.5.4.2 </span>Classes</a></li><li class="subtoc"></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h5><span class="bookmarklink"><a class="bookmarklink" href="#IMEL" title="link to this section "><span class="invisible">TEI: Elements</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.5.4.3 </span><span class="head">Elements</span></h5><p>An <a class="gi" title="(element specification) documents the structure, content, and purpose of a single element type." href="ref-elementSpec.html">elementSpec</a> produces a RELAX NG specification in two parts; firstly, it must generate an <span class="gi"><rng:define></span> pattern by which other elements can refer to it, and then it must generate an <span class="gi"><rng:element></span> with the content model and attributes. It may be convenient to make two separate patterns, one for the element's attributes and one for its content model.</p><p>The content model is created by processing the TEI declarations found within the <a class="gi" title="(content model) contains the text of a declaration for the schema documented." href="ref-content.html">content</a> element; ; the attributes are processed in the same way as those from attribute classes, described above.</p></div></div><div class="teidiv2" id="IM-makeDTD"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#IMRN"><span class="headingNumber">23.5.4 </span>Making a RELAX NG Schema</a></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#IMGD"><span class="headingNumber">23.5.6 </span>Generating Documentation</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h4><span class="bookmarklink"><a class="bookmarklink" href="#IM-makeDTD" title="link to this section "><span class="invisible">TEI: Making a DTD</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.5.5 </span><span class="head">Making a DTD</span></h4><p>Generation of DTDs largely follows the same pattern as RELAX NG generation, with one important exception—<span class="hi">the order of declaration matters</span>. A DTD may not refer to an entity which has not yet been declared. Since both macros and classes generate DTD parameter entities, the TEI Guidelines are constructed so that they can be declared in the right order. A processor must therefore work in the following order: </p><ol class="numbered"><li class="item">declare all model classes which have a <span class="att">predeclare</span> value of <span class="val">true</span></li><li class="item">declare all macros which have a <span class="att">predeclare</span> value of <span class="val">true</span></li><li class="item">declare all other classes</li><li class="item">declare the modules (if DTD fragments are being constructed)</li><li class="item">declare any remaining macros</li><li class="item">declare the elements and their attributes</li></ol><p> </p><div class="p">Let us consider a complete example, a simple element with no attributes of its own: <div id="index-egXML-d52e152830" class="pre egXML_valid"><span class="element"><elementSpec <span class="attribute">module</span>="<span class="attributevalue">namesdates</span>"<br /> <span class="attribute">ident</span>="<span class="attributevalue">faith</span>"></span><br /> <span class="element"><desc></span>specifies the faith, religion, or belief set of a person.<span class="element"></desc></span><br /> <span class="element"><classes></span><br /> <span class="element"><memberOf <span class="attribute">key</span>="<span class="attributevalue">model.persStateLike</span>"/></span><br /> <span class="element"><memberOf <span class="attribute">key</span>="<span class="attributevalue">att.editLike</span>"/></span><br /> <span class="element"><memberOf <span class="attribute">key</span>="<span class="attributevalue">att.datable</span>"/></span><br /> <span class="element"></classes></span><br /> <span class="element"><content></span><br /> <span class="element"><macroRef <span class="attribute">key</span>="<span class="attributevalue">macro.phraseSeq</span>"/></span><br /> <span class="element"></content></span><br /><span class="element"></elementSpec></span></div> If DTD fragments are being generated (for use as described in <a class="link_ptr" href="USE.html#STPE" title="Using TEI Parameterized Schema Fragments"><span class="headingNumber">23.5.7 </span>Using TEI Parameterized Schema Fragments</a>), this will result in the following: <pre class="pre_eg cdata"><!ENTITY % faith 'INCLUDE' >
<![ %faith; [
<!--doc:specifies the faith, religion, or belief set of a person. -->
<!ELEMENT %n.faith; %om.RR; %macro.phraseSeq;>
<!ATTLIST %n.faith; xmlns CDATA "http://www.tei-c.org/ns/1.0">
<!ATTLIST %n.faith;
%att.global.attributes;
%att.editLike.attributes;
%att.datable.attributes; >
]]>
</pre> Here the whole stanza is contained in a marked section (for use as described in <a class="link_ptr" href="USE.html#STPEEX" title="Inclusion and Exclusion of Elements"><span class="headingNumber">23.5.7.2 </span>Inclusion and Exclusion of Elements</a>), the element name is parameterized (see <a class="link_ptr" href="USE.html#STPEGI" title="Changing the Names of Generic Identifiers"><span class="headingNumber">23.5.7.3 </span>Changing the Names of Generic Identifiers</a>), and the class attributes are entity references derived from the <a class="gi" title="specifies class membership of the documented element or class." href="ref-memberOf.html">memberOf</a> records in <a class="gi" title="specifies all the classes of which the documented element or class is a member or subclass." href="ref-classes.html">classes</a>. Note the additional attribute which provides a default <span class="att">xmlns</span> declaration for the element; the effect of this is that if the document is processed by a DTD-aware XML processor, the namespace declaration will be present automatically without the document author even being aware of it.</div><p>A simpler rendition for a flattened DTD generated from a customization will result in the following, with no containing marked section, and no parameterized name: </p><pre class="pre_eg cdata">
<!ELEMENT faith %macro.phraseSeq;>
<!ATTLIST faith xmlns CDATA "http://www.tei-c.org/ns/1.0">
<!ATTLIST faith
%att.global.attribute.xmlspace;
%att.global.attribute.xmlid;
%att.global.attribute.n;
%att.global.attribute.xmllang;
%att.global.attribute.rend;
%att.global.attribute.xmlbase;
%att.global.linking.attribute.corresp;
%att.global.linking.attribute.synch;
%att.global.linking.attribute.sameAs;
%att.global.linking.attribute.copyOf;
%att.global.linking.attribute.next;
%att.global.linking.attribute.prev;
%att.global.linking.attribute.exclude;
%att.global.linking.attribute.select;
%att.editLike.attribute.cert;
%att.editLike.attribute.resp;
%att.editLike.attribute.evidence;
%att.datable.w3c.attribute.period;
%att.datable.w3c.attribute.when;
%att.datable.w3c.attribute.notBefore;
%att.datable.w3c.attribute.notAfter;
%att.datable.w3c.attribute.from;
%att.datable.w3c.attribute.to;>
</pre><p> Here the attributes from classes have been expanded into individual entity references.</p></div><div class="teidiv2" id="IMGD"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#IM-makeDTD"><span class="headingNumber">23.5.5 </span>Making a DTD</a></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#STPE"><span class="headingNumber">23.5.7 </span>Using TEI Parameterized Schema Fragments</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h4><span class="bookmarklink"><a class="bookmarklink" href="#IMGD" title="link to this section "><span class="invisible">TEI: Generating Documentation</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.5.6 </span><span class="head">Generating Documentation</span></h4><p>In Donald Knuth's literate programming terminology (<a class="link_ptr" href="BIB.html#KNUTH" title="Knuth Donald E. Literate ProgrammingCSLI Lecture Notes 270937073806Stanford CaliforniaCenter for the Study of Language and Info...">Knuth (1992)</a>), the previous sections have dealt with the <span class="term">tangle</span> process; to generate documentation, we now turn to the <span class="term">weave</span> process.</p><p>An ODD customization may consist largely of general documentation and examples, requiring no ODD-specific processing. It will normally however also contain a <a class="gi" title="(schema specification) generates a TEI-conformant schema and documentation for it." href="ref-schemaSpec.html">schemaSpec</a> element and possibly some <a class="gi" title="(specification group) contains any convenient grouping of specifications for use within the current module." href="ref-specGrp.html">specGrp</a> fragments.</p><p>The generated documentation may be of two forms. On the one hand, we may document the customization itself, that is, only those elements (etc.) which differ in their specification from that provided by the TEI reference documentation. Alternatively, we may generate reference documentation for the complete subset of the TEI which results from applying the customization. The TEI Roma tools take the latter approach, and operate on the result of the first stage processing described in <a class="link_ptr" href="USE.html#IM-unified" title="Making a Unified ODD"><span class="headingNumber">23.5.1 </span>Making a Unified ODD</a>.</p><p>Generating reference documentation for <a class="gi" title="(element specification) documents the structure, content, and purpose of a single element type." href="ref-elementSpec.html">elementSpec</a>, <a class="gi" title="(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." href="ref-classSpec.html">classSpec</a>, and <a class="gi" title="(macro specification) documents the function and implementation of a pattern." href="ref-macroSpec.html">macroSpec</a> elements is largely dependent on the design of the preferred output. Some applications may, for example, want to turn all names of objects into hyperlinks, show lists of class members, or present lists of attributes as tables, lists, or inline prose. Another technique implemented in these Guidelines is to show lists of potential ‘parents’ for each element, by tracing which other elements have them as possible members of their content models.</p><p>One model of display on a web page is shown in <a class="link_ptr" href="USE.html#ref-faith" title="Example reference documentation for faith">Figure 23.1, Example reference documentation for faith</a>, corresponding to the <a class="gi" title="specifies the faith, religion, or belief set of a person." href="ref-faith.html">faith</a> element shown in section <a class="link_ptr" href="USE.html#IM-makeDTD" title="Making a DTD"><span class="headingNumber">23.5.5 </span>Making a DTD</a>.</p><figure class="figure" id="ref-faith"><img src="Images/ref-faith.png" alt="Example reference documentation for " class="graphic" style=" width:450px;" /><figcaption class="caption">Figure 23.1. Example reference documentation for <span class="gi"><faith></span></figcaption></figure></div><div class="teidiv2" id="STPE"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#IMGD"><span class="headingNumber">23.5.6 </span>Generating Documentation</a></li><li class="subtoc"></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h4><span class="bookmarklink"><a class="bookmarklink" href="#STPE" title="link to this section "><span class="invisible">TEI: Using TEI Parameterized Schema Fragments</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.5.7 </span><span class="head">Using TEI Parameterized Schema Fragments</span></h4><p>The TEI parameterized DTD and RELAX NG fragments make use of parameter entities and patterns for several purposes. In this section we describe their interface for the user. In general we recommend use of ODD instead of this technique, which has been retained only for compatability reasons.</p><div class="div3" id="STPED"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#STPEEX"><span class="headingNumber">23.5.7.2 </span>Inclusion and Exclusion of Elements</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h5><span class="bookmarklink"><a class="bookmarklink" href="#STPED" title="link to this section "><span class="invisible">TEI: Selection of Modules</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.5.7.1 </span><span class="head">Selection of Modules</span></h5><p>Special-purpose parameter entities are used to specify which modules are to be combined into a TEI DTD. They take the form <span class="val">TEI.xxxxx</span> where <code>xxxx</code> is the name of the module as given in table <a class="link_ptr" href="ST.html#tab-mods" title="Module nameFormal public identifierWhere definedanalysisAnalysis and InterpretationcertaintyCertainty and UncertaintycoreCommon...">Table 2</a> in <a class="link_ptr" href="ST.html#STMA" title="TEI Modules"><span class="headingNumber">1.1 </span>TEI Modules</a>. For example, the parameter entity <span class="ident-pe">TEI.linking</span> is used to define whether or not to include the module <span class="ident-module">linking</span>. All such parameter entities are declared by default with the value <span class="val">IGNORE</span>: to select a module, therefore, the encoder declares the appropriate parameter entities with the value <span class="val">INCLUDE</span>.</p><p>For XML DTD fragments, note that some modules generate two DTD fragments: for example the <span class="ident-module">analysis</span> module generates fragments called <span class="ident-frag">analysis-decl</span> and <span class="ident-frag">analysis</span>. This is because the declarations they contain are needed at different points in the creation of an XML DTD.</p><p>The parameter entity named for the module is used as the keyword controlling a conditional marked section in the DTD fragment generated by the <span class="ident-module">tei</span> module. The declarations for each DTD fragment constituting the module are contained within such marked sections. For example, the parameter entity <span class="ident-pe">TEI.linking</span> appears twice in <span class="ident-file">tei.dtd</span>, once for the <span class="ident-frag">linking-decl</span> schema fragment: </p><pre class="pre_eg cdata">
<!ENTITY % TEI.linking 'IGNORE' >
<![%TEI.linking;[
<!ENTITY % file.linking-decl PUBLIC '-//TEI P5//ENTITIES Linking, Segmentation, and Alignment//EN' 'linking-decl.dtd' >
%file.linking-decl;
]] ></pre><p> and once for the <span class="ident-frag">linking</span> schema fragment: </p><pre class="pre_eg cdata">
<![%TEI.linking;[
<!ENTITY % file.linking PUBLIC '-//TEI P5//ELEMENTS Linking, Segmentation, and Alignment//EN' 'linking.dtd' >
%file.linking;
]] ></pre><p> If TEI.linking has its default value of IGNORE, neither declaration has any effect. If however it has the value INCLUDE, then the content of each marked section is acted upon: the parameter entities <span class="ident-pe">file.linking</span> and <span class="ident-pe">file.linking-decl</span> are referenced, which has the effect of embedding the content of the files they represent at the appropriate point in the DTD.</p><p>The RELAX NG schema fragments can be combined in a wrapper schema using the standard mechanism of <span class="gi"><rng:include></span> in that language.</p></div><div class="div3" id="STPEEX"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#STPED"><span class="headingNumber">23.5.7.1 </span>Selection of Modules</a></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#STPEGI"><span class="headingNumber">23.5.7.3 </span>Changing the Names of Generic Identifiers</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h5><span class="bookmarklink"><a class="bookmarklink" href="#STPEEX" title="link to this section "><span class="invisible">TEI: Inclusion and Exclusion of Elements</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.5.7.2 </span><span class="head">Inclusion and Exclusion of Elements</span></h5><p>The TEI DTD fragments also use marked sections and parameter entity references to allow users to exclude the definitions of individual elements, in order either to make the elements illegal in a document or to allow the element to be redefined. The parameter entities used for this purpose have exactly the same name as the generic identifier of the element concerned. The default definition for these parameter entities is <span class="val">INCLUDE</span> but they may be changed to <span class="val">IGNORE</span> in order to exclude the standard element and attribute definition list declarations from the DTD.</p><p>The declarations for the element <a class="gi" title="(paragraph) marks paragraphs in prose." href="ref-p.html">p</a>, for example, are preceded by a definition for a parameter entity with the name <span class="ident-ge">p</span> and contained within a marked section whose keyword is given as <code>%p;</code>: </p><pre class="pre_eg cdata"><!ENTITY % p 'INCLUDE' >
<![ %p; [
<!-- element and attribute list declaration for p here -->
]]</pre><p>These parameter entities are defined immediately preceding the element whose declarations they control; because their names are completely regular, they are not documented further. </p><p>To define a DTD in which the element <a class="gi" title="(paragraph) marks paragraphs in prose." href="ref-p.html">p</a> is excluded therefore, the entity <span class="ident-pe">p</span> needs to be redefined as <span class="val">IGNORE</span> by ensuring that a declaration such as </p><pre class="pre_eg cdata"><!ENTITY % p 'IGNORE' ></pre><p> is added earlier in the DTD than the default (see further <a class="link_ptr" href="USE.html#STOVLO" title="Embedding Local Modifications (DTD only)"><span class="headingNumber">23.5.7.4 </span>Embedding Local Modifications (DTD only)</a>).</p><p>Similarly, in the parameterized RELAX NG schemas, every element is defined by a pattern named after the element. To undefine an element therefore all that is necessary is to add a declaration like the following: </p><pre class="pre_eg cdata"> p = notAllowed </pre></div><div class="div3" id="STPEGI"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#STPEEX"><span class="headingNumber">23.5.7.2 </span>Inclusion and Exclusion of Elements</a></li><li class="subtoc"><span class="nextLink"> » </span><a class="navigation" href="USE.html#STOVLO"><span class="headingNumber">23.5.7.4 </span>Embedding Local Modifications (DTD only)</a></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h5><span class="bookmarklink"><a class="bookmarklink" href="#STPEGI" title="link to this section "><span class="invisible">TEI: Changing the Names of Generic Identifiers</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.5.7.3 </span><span class="head">Changing the Names of Generic Identifiers</span></h5><p>In the TEI DTD fragments, elements are not referred to directly by their generic identifiers; instead, the DTD fragments refer to parameter entities which expand to the standard generic identifiers. This allows users to rename elements by redefining the appropriate parameter entity. Parameter entities used for this purpose are formed by taking the standard generic identifier of the element and attaching the string <span class="val">n.</span> as a prefix. Thus the standard generic identifiers for paragraphs, notes, and quotations, <a class="gi" title="(paragraph) marks paragraphs in prose." href="ref-p.html">p</a>, <a class="gi" title="contains a note or annotation." href="ref-note.html">note</a>, and <a class="gi" title="(personal name) contains a proper noun or proper-noun phrase referring to a person, possibly including one or more of the person's forenames, surnames, honorifics, added names, etc." href="ref-persName.html">persName</a> are defined by declarations of the following form: </p><pre class="pre_eg cdata"><!ENTITY % n.p "p">
<!ENTITY % n.note "note">
<!ENTITY % n.persName "persName"></pre><p> Note that since all names are case-sensitive, the specific mix of uppercase and lowercase letters in the standard generic identifier must be preserved in the entity name.</p><p>These declarations are generated by an ODD processor when TEI DTD fragments are created. </p><p>In the RELAX NG schemas, all elements are normally defined using a pattern with the same name as the element (as described in <a class="link_ptr" href="USE.html#IM-naming" title="Names and Documentation in Generated Schemas"><span class="headingNumber">23.5.3 </span>Names and Documentation in Generated Schemas</a>): for example </p><pre class="pre_eg cdata">
abbr = element abbr { abbr.content, abbr.attributes }
</pre><p> The easiest way of renaming the element is thus simply to rewrite the pattern with a different element name; any references use the pattern, not the element, name. </p><pre class="pre_eg cdata">
abbr = element abbrev { abbr.content, abbr.attributes }
</pre><p> More complex revisions, such as redefining the content of the element (defined by the pattern <span class="ident-rng">abbr.content</span>) or its attributes (defined by the pattern <span class="ident-rng">abbr.attributes</span>) can be accomplished in a similar way, using the features of the RELAX NG language. The recommended method of carrying out such modifications is however to use the ODD language as further described in section <a class="link_ptr" href="TD.html" title="27"><span class="headingNumber">22 </span>Documentation Elements</a>.</p></div><div class="div3" id="STOVLO"><div class="miniTOC miniTOC_right"><ul class="subtoc"><li class="subtoc"><span class="previousLink"> « </span><a class="navigation" href="USE.html#STPEGI"><span class="headingNumber">23.5.7.3 </span>Changing the Names of Generic Identifiers</a></li><li class="subtoc"></li><li class="subtoc"><a class="navigation" href="index.html">Home</a></li></ul></div><h5><span class="bookmarklink"><a class="bookmarklink" href="#STOVLO" title="link to this section "><span class="invisible">TEI: Embedding Local Modifications (DTD only)</span><span class="pilcrow">¶</span></a></span><span class="headingNumber">23.5.7.4 </span><span class="head">Embedding Local Modifications (DTD only)</span></h5><p>Any local modifications to a DTD (i.e. changes to a schema other than simple inclusion or exclusion of modules) are made by declarations stored in one of two local extension files, one containing modifications to the TEI parameter entities, and the other new or changed declarations of elements and their attributes. Entity declarations must be made which associate the names of these two files with the appropriate parameter entity so that the declarations they contain can be embedded within the TEI DTD at an appropriate point.</p><p>The following entities are referred to by the main <span class="ident-file">tei.dtd</span> file to embed portions of the TEI DTD fragments or locally developed extensions. </p><dl><dt><span><span class="ident-pe">TEI.extensions.ent</span></span></dt><dd>identifies a local file containing extensions to the TEI parameter entities</dd><dt><span><span class="ident-pe">TEI.extensions.dtd</span></span></dt><dd>identifies a local file containing extensions to the TEI module</dd></dl><p>For example, if the relevant files are called <span class="ident-file">project.ent</span> and <span class="ident-file">project.dtd</span>, then declarations like the following would be appropriate: </p><pre class="pre_eg cdata"><!ENTITY % TEI.extensions.ent SYSTEM 'project.ent' >
<!ENTITY % TEI.extensions.dtd SYSTEM 'project.dtd' ></pre><p>When an entity is declared more than once, the first declaration is binding and the others are ignored. The local modifications to parameter entities should therefore be handled before the standard parameter entities themselves are declared in <span class="ident-file">tei.dtd</span>. The entity <span class="ident-pe">TEI.extensions.ent</span> is referred to before any TEI declarations are handled, to allow the user's declarations to take priority. If the user does not provide a <span class="ident-pe">TEI.extensions.ent</span> entity, the entity will be expanded to the empty string.</p><p>For example the encoder might wish to add two phrase-level elements <span class="gi"><it></span> and <span class="gi"><bd></span>, perhaps as synonyms for <span class="tag"><hi rend='italics'></span> and <span class="tag"><hi rend='bold'></span>. As described in chapter <a class="link_ptr" href="USE.html#MD" title="Customization"><span class="headingNumber">23.3 </span>Customization</a>, this involves two distinct steps: one to define the new elements, and the other to ensure that they are placed into the TEI document structure at the right place.</p><p>Creating the new declarations is done in the same way for user-defined elements as for any other; the same parameter entities need to be defined so that they may be referenced by other elements. The content models of these new elements may also reference other parameter entities, which is why they need to be declared after other declarations. </p><p>The second step involves modifying the element class to which the new elements should be attached. This requires that the parameter entity <span class="ident-pe">macro.phraseSeq</span> should be modified to include the generic identifiers for the new elements we wish to create. The declaration for each modifiable parameter entity in the DTD includes a reference to an additional parameter entity with the same name prefixed by an <code>x.</code>; these entities are declared by default as the null string. However, in the file containing local declarations they may be redeclared to include references to the new class members: </p><pre class="pre_eg cdata"><!ENTITY % x.macro.phraseSeq 'it | bd |'></pre><p> and this declaration will take precedence over the default when the declaration for macro.phraseSeq is evaluated.</p></div></div></div></div><nav class="left"><span class="upLink"> ↑ </span><a class="navigation" href="index.html">TEI P5 Guidelines</a><span class="previousLink"> « </span><a class="navigation" href="TD.html"><span class="headingNumber">22 </span>Documentation Elements</a><span class="nextLink"> » </span><a class="navigation" href="REF-CLASSES-MODEL.html"><span class="headingNumber">Appendix A </span>Model Classes</a></nav><!--Notes in [div]--><div class="notes"><div class="noteHeading">Notes</div><div class="note" id="Note126"><span class="noteLabel">89 </span><div class="noteBody">Excluding <a class="link_odd" title="groups elements used to represent individual non-Unicode characters or glyphs." href="ref-model.gLike.html">model.gLike</a> is generally inadvisable however, since without it the resulting schema has no way of referencing non-Unicode characters.</div> <a class="link_return" title="Go back to text" href="#Note126_return">↵</a></div><div class="note" id="Note127"><span class="noteLabel">90 </span><div class="noteBody">This is not strictly the case, since the element <a class="gi" title="(example of XML) a single XML fragment demonstrating the use of some XML, such as elements, attributes, or processing instructions, etc., in which the <egXML> element functions as the root element." href="ref-egXML.html">egXML</a> used to represent TEI examples has its own namespace, <span class="val">http://www.tei-c.org/ns/Examples</span>; this is the only exception however.</div> <a class="link_return" title="Go back to text" href="#Note127_return">↵</a></div><div class="note" id="Note128"><span class="noteLabel">91 </span><div class="noteBody">Full namespace support does not exist in the DTD language, and therefore these techniques are available only to users of more modern schema languages such as RELAX NG or W3C Schema.</div> <a class="link_return" title="Go back to text" href="#Note128_return">↵</a></div><div class="note" id="Note129"><span class="noteLabel">92 </span><div class="noteBody">This module can be used to document any XML schema, and has indeed been used to document several non-TEI schemas.</div> <a class="link_return" title="Go back to text" href="#Note129_return">↵</a></div><div class="note" id="Note130"><span class="noteLabel">93 </span><div class="noteBody">Here and elsewhere we use the word <span class="mentioned">schema</span> to refer to any formal document grammar language, irrespective of the formalism used to represent it.</div> <a class="link_return" title="Go back to text" href="#Note130_return">↵</a></div><div class="note" id="Note131"><span class="noteLabel">94 </span><div class="noteBody">An ODD processor should recognize as erroneous such obvious inconsistencies as an attempt to include an <a class="gi" title="(element specification) documents the structure, content, and purpose of a single element type." href="ref-elementSpec.html">elementSpec</a> in <span class="val">add</span> mode for an element which is already present in an imported module.</div> <a class="link_return" title="Go back to text" href="#Note131_return">↵</a></div><div class="note" id="Note132"><span class="noteLabel">95 </span><div class="noteBody">The carthago program behind the Pizza Chef application, written by Michael Sperberg-McQueen for TEI P3 and P4, went to very great efforts to get this right. The XSLT transformations used by the P5 Roma application are not as sophisticated, partly because the RELAX NG language is more forgiving than DTDs.</div> <a class="link_return" title="Go back to text" href="#Note132_return">↵</a></div><div class="note" id="Note133"><span class="noteLabel">96 </span><div class="noteBody">Note that deletion of required elements will cause the schema specification to accept as valid documents which cannot be TEI-conformant, since they no longer conform to the TEI Abstract Model; conformance topics are addressed in more detail in <a class="link_ptr" href="USE.html#CF" title="Conformance"><span class="headingNumber">23.4 </span>Conformance</a>.</div> <a class="link_return" title="Go back to text" href="#Note133_return">↵</a></div></div><div class="stdfooter autogenerated"><p>
[<a href="../../en/html/USE.html">English</a>]
[<a href="../../de/html/USE.html">Deutsch</a>]
[<a href="../../es/html/USE.html">Español</a>]
[<a href="../../it/html/USE.html">Italiano</a>]
[<a href="../../fr/html/USE.html">Français</a>]
[<a href="../../ja/html/USE.html">日本語</a>]
[<a href="../../ko/html/USE.html">한국어</a>]
[<a href="../../zh-TW/html/USE.html">中文</a>]
</p><hr /><div class="footer"><a class="plain" href="http://www.tei-c.org/About/">TEI Consortium</a> | <a class="plain" href="http://www.tei-c.org/About/contact.xml">Feedback</a></div><hr /><address><br />TEI Guidelines <a class="link_ref" href="AB.html#ABTEI4">Version</a> <a class="link_ref" href="../../readme-3.1.1.html">3.1.1a</a>. Last updated on <span class="date">10th May 2017</span>, revision <a class="link_ref" href="https://github.com/TEIC/TEI/commit/bd8dda3">bd8dda3</a>. This page generated on 2017-05-12T12:30:09Z.</address></div></div></body></html>