For ease of discussion, we distinguish the following different kinds of modification: deletion of elements; renaming of elements; modification of content models; modification of attribute and attribute-value lists; modification of class membership; addition of new elements. Each of these is described in the following sections.

Each kind of modification changes the set of documents that will be considered valid according to the resulting schema. Any combination of unchanged TEI modules may be thought of as defining a certain set of documents. Each schema resulting from a modified combination of TEI modules will define a different set of documents. The set of documents valid according to the unmodified schema may or may not be properly contained in the set of documents considered to be valid according to the modified schema. We use the term clean modification to describe a modification which regards as valid a subset of the documents considered valid by the same combination of TEI modules unmodified. Alternatively, the set of documents considered valid by the original schema might be disjoint from the set of documents considered valid by the modified schema, with neither being properly contained by the other. Modifications that have this result are called unclean modifications. 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.

Cleanliness can only be assessed with reference to elements in the TEI namespace.

All the elements defined by the TEI scheme are labelled as belonging to a single namespace, maintained by the TEI and with the URI http://www.tei-c.org/ns/1.0.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 the only exception however. Only elements which are unmodified or which have undergone a clean modification may use this namespace. In a TEI-conformant document, it is assumed that all attributes not explicitly labelled with a namespace (such as, for example xml:id) also belong to the TEI namespace, and are defined by the TEI.

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 ns attribute is provided on elements schemaSpec, elementSpec, and attDef for this purpose.

Suppose, for example, that we wish to add a new attribute topic to the existing TEI element p. In the absence of namespace considerations, this would be an unclean modification, since p 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: indicates the topic of a TEI paragraph

Document instances using a schema derived from this ODD can now indicate clearly the status of this attribute:

Since topic 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.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.

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 name space or to no name space at all.

If the ns attribute is supplied on a schemaSpec 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 schemaSpec. This can be useful if it is desired simply to avoid namespace processing. For example, the following schema specification results in a schema called noName which has no namespace, even though it comprises declarations from the TEI header module:

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 schema specification using the Chinese translation, for example, would use the namespace http://www.tei-c.org/ns/1.0/zh

The elements used to define a TEI customization (schemaSpec, moduleRef, elementSpec, 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 .This module can be used to document any XML schema, and has indeed been used to document several non-TEI schemas.

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 desc element of an unmodified TEI elementSpec may describe an element in terms more general than appropriate to a particular project, or the exemplum elements within it may not illustrate the project's actual intended usage of the element, or the remarks element may contain discussions of matters irrelevant to the project. These elements may therefore be replaced or deleted within an elementSpec as necessary.

Radical revision is also possible. It is feasible to produce a modification in which the teiHeader or text 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 TEI conformance in the next section, .

Several examples of customizations of the TEI are provided as part of the standard release. They include the following: tei_bare The schema generated from this customization is the minimum needed for TEI Conformance. It provides only a handful of elements. tei_all The schema generated from this customization combines all available TEI modules, providing elements. tei_allPlus The schema generated from this customization combines all available TEI modules with three other non-TEI vocabularies, specifically MathML, SVG, and XInclude.

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.

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 . The tutorial and associated schema specification is also included as one of the exemplars provided with TEI P5.

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 as well as including the (non-TEI) module defining the RELAX NG language. This enables schemas derived from this customization file to validate examples contained within them in a number of ways, further described within the document.

These Guidelines mandate the use of well-formed XML as representation format. Documents must conform to the World Wide Web Consortium recommendation of the or successor editions found at http://www.w3.org/TR/xml/. 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 are at best TEI-conformable, and cannot be considered in any way TEI-conformant.

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.

A TEI-conformant document must use the TEI namespace, and therefore must also include an XML-conformant namespace declaration, as defined below ().

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 .

In addition to the well-formedness criterion, the W3C defines the notion of a valid document, as being a well-formed document which matches a specific set of rules or syntactic constraints, defined by a schema. 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 the Guidelines define.

All TEI-conformant 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 . We call the formal output of this process a TEI Schema.

The TEI does not mandate use of any particular schema language, only that this schemaHere and elsewhere we use the word schema to refer to any formal document grammar language, irrespective of the formalism used to represent it. should have been generated from a TEI ODD file 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; in particular the DTD language does not fully support namespaces. Features which cannot be represented in all schema languages are documented in chapters and .

As noted in section , many varieties of TEI schema are possible and not all of them are necessarily TEI-conformant; derivation from an ODD is a necessary but not a sufficient condition for TEI Conformance.

The TEI Abstract Model is the conceptual schema instantiated by the TEI Guidelines. These Guidelines define, both formally and informally, a set of abstract concepts such as paragraph or heading, and their structural relationships, for example stating that paragraphs do not contain headings. 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.

The Namespaces Recommendation of the W3C () 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.

Essentially all elements in a TEI Schema which represents concepts from the TEI Abstract Model belong to the TEI namespace, http://www.tei-c.org/ns/1.0, 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.

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, though it may be TEI-conformable. 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.

As noted in 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 TEI ODD file 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 TEI Customization exemplar ODD files and the schemas already generated from them (see ), 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 TEI ODD file.

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.

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. The status of such a schema with respect to the tei_all schema cannot however be determined, in general; it may therefore be impossible 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.

The conformance status of a given document may be assessed by answering the following questions, in the order indicated: 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. 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. Does the markup in the document correctly represent the TEI abstract model? Though difficult to assess, this is essential to TEI conformance. 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. 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. 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. Is the document valid according to the schema derived from its associated ODD specification, but not according to tei_all? If so, the document uses a TEI extension. Is it possible automatically to transform the document into a document which is valid according to tei_all, using only information supplied in the accompanying ODD and without loss of information? If so, the document is TEI-conformable.

In the following table, we examine more closely some specific, though imaginary, cases: A B C D E F G H Conforms to TEI Abstract Model Y N Y Y ? Y N ? Valid ODD present Y Y Y Y Y Y Y N Uses only non-TEI namespace(s) or none N N N N Y N Y N Uses TEI and other namespaces correctly Y Y N Y N Y N Y Document is valid as a subset of tei_all Y N Y N N Y N Y Document can be converted automatically to a form which is valid as a subset of tei_all Y N Y N N Y N ?

We assume firstly that each sample document assessed here is a well-formed XML document, and that it is valid against some schema.

The document in column A is TEI-conformant. Its tagging follows the TEI Abstract Model, both as regards syntactic constraints (its l elements appear within div elements and not the reverse) and semantic constraints (its l 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 tei_all schema.

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 p to permit div within it, and it includes an element pageTrimming which appears to have the same meaning as the existing TEI fw 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.

The document in column C is TEI-conformable. It is almost the same as the document in column A, except that the names of the elements used are not those specified by the TEI namespace. Because the ODD accompanying it contains an exact mapping for each element name (using the altIdent element) and there are no name conflicts, it is possible to make an automatic conversion of this document.

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 blort 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 tei_all. If the associated ODD provided a way of mapping this element to an existing TEI element, then this would be TEI-conformable.

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 p within it is the same as the TEI's p 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 p 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.

The document in column F is TEI-conformable. The difference between it and that in column D is that the new element blort 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 my:blort may be automatically converted to a tei:seg type="blort", for example). For this to work, however, the blort must observe the same syntactic constraints as the seg; if it does not, this would also be a case of TEI Extension.

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.

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 tei_all, 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.

An ODD customization must contain a single schemaSpec element, which defines the schema to be constructed. Amongst other attributes inherited from the att.identified class, this element also carries a required ident 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 ns attribute may be used to specify the default namespace within which elements valid against the resulting schema belong, as discussed in .

The schemaSpec element contains an unordered series of specialized elements, each of which is of one of the following four types: specifications elements from the class model.oddDecl (by default elementSpec, classSpec, moduleSpec, and macroSpec); these must have a mode attribute which determines how they will be processed.An ODD processor should recognize as erroneous such obvious inconsistencies as an attempt to include an elementSpec in add mode for an element which is already present in an imported module. If the value of mode is add, then the object is simply copied to the output, but if it is change, delete, or replace, then it will be looked at by other parts of the process. references to specifications specGrpRef elements refer to specGrp elements that occur elsewhere in this, or another, document. A specGrp element, in turn, groups together a set of ODD specifications (among other things, including further specGrpRef elements). The use of specGrp and specGrpRef permits the ODD markup to occur at the points in documentation where they are discussed, rather than all inside schemaSpec. The target attribute of any specGrpRef should be followed, and the elementSpec, classSpec, and macroSpec, elements in the corresponding specGrp should be processed as described in the previous item; specGrpRef elements should be processed as described here. references to TEI Modules moduleRef elements with key attributes refer to components of the TEI. The value of the key attribute matches the ident attribute of the moduleSpec element defining a TEI module. The key 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 schemaSpec being processed. references to external modules a moduleRef element may also refer to a compatible external module by means of its url 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.

Each object obtained from the TEI ODD specification using moduleRef by means of the key attribute must be checked against objects in the customization schemaSpec according to the following rules: if there is an object in the ODD customization with the same value for the ident attribute, and a mode value of delete, then the object from the module is ignored; if there is an object in the ODD customization with the same value for the ident attribute, and a mode value of replace, then the object from the module is ignored, and the one from the ODD customization is used in its place; if there is an object in the ODD customization with the same value for the ident attribute, and a mode value of change, then the two objects must be merged, as described below; if there is an object in the ODD customization with the same value for the ident attribute, and a mode value of add, then an error condition should be raised; otherwise, the object from the module is copied to the result.

To merge two objects with the same ident, their component attributes and child elements must be looked at recursively. Each component may fall into one of the following four categories: Some components may occur only once within the merged object (for example attributes, and altIdent, content, or classes 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. Some components are grouping objects (attList, valList, for example); these are always copied to the output, and their children are then processed following the rules given in this list. Some components are identifiable: this means that they are members of the att.identified class from which they inherit the ident attribute; examples include attDef and valItem. A component of this type will be processed according to its mode attribute, following the rules given above. Some components may occur multiple times, but are neither grouped nor identifiable. Examples include the members of model.glossLike such as equiv, desc, gloss, the exemplum, remarks, listRef, datatype or defaultVal elements. These should be copied from both the TEI ODD specification and the ODD customization, and all occurrences included in the output.

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: The effect of its membership in the att.typed class is to provide p with a type attribute and a subtype attribute. If we wish p to not have subtype, we could extend the customization in our schema as follows: This means that when memberOf key="att.typed"/ 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 attRef 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.

The effect of the concatenation of unidentifiable components should be considered carefully. An original may have marks paragraphs in prose. which would usefully be extended with this: marca párrafos en prosa. to provide an alternate description in another language. Nothing prevents the user from supplying desc several times in the same language, and subsequent applications will have to decide what that may mean.

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 elementSpec in replace mode, since the exemplum element is not identifiable.

In the processing of the content models of elements and the content of macros, deleted elements may require special attention.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. A content model like this: requires no special treatment because everything is expressed in terms of model classes; if deletions result in model.personPart having no members, then model.global is left as the only child of rng:choice. An ODD processor may or may not elect to simplify the resulting choice between nothing and model.global by removing the wrapper rng:choice element. However, such simplification may be considerably more complex in the general case (if for example the rng:choice is itself inside an rng:zeroOrMore inside a rng:group), 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.

If an element refers directly to an element child, like this: and figDesc has been deleted,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 . it will be necessary to remove that reference, or the resulting schema will be invalid. Surrounding constructs, such as a rng:zeroOrMore (which cannot be empty), may also have to be removed.

The result of the work carried out should be a new schemaSpec which contains a complete and internally consistent set of element, class, and macro specifications, possibly also including moduleRef elements with url attributes identifying external modules.

Assuming that any modifications have been resolved, as outlined in the previous section, making a schema is now a four stage process: all datatype and other macro specifications must be collected together and declared at the start of the output schema; all classes must be declared in the right order (since some classes reference others, the order is significant); all elements are declared; any moduleRef elements with a url attribute identifying an external schema must be processed. 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.

An ODD processor may use any desired schema language or languages for its schema output. The TEI ODD specification uses RELAX NG to express content models, and is therefore biased towards this language. However, the current TEI ODD processing system is capable of producing schema output in the three main schema languages, as follows: A RELAX NG (XML) schema is generated by creating wrappers around the content models taken directly from the ODD specification; a version re-expressed in the RELAX NG compact syntax is generated using James Clark's trang application. 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. A W3C Schema schema is created by generating a RELAX NG schema and then using James Clark's trang application. 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 trang is able to translate properly (see further below)—this may involve simple trial and error.

Other projects may decide to follow a different route, perhaps implementing a direct ODD to W3C Schema translator.

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.

The difference between the schema styles may be illustrated by considering this ODD specification: A simple rendering to RELAX NG produces this: In the above, a subsequent redefinition of the attribute class (such as att.global) would have no effect, since references to such classes have been expanded to reference their constituent attributes.

The equivalent parameterized version might look like this: Here, the attribute class att.global is provided via an explicit reference (att.global.attributes), and can therefore be redefined. Moreover, the attributes are separated from the content model, allowing either to be overridden.

In the remainder of these section, the terms simple schema and parameterized schema 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.

Thirdly, the problem of missing components must be resolved. For example, consider this (fictitious) model for sp: This proposes anything from the global model class, followed by some speaker elements, followed by anything from the model.global class. What happens if speaker is removed? The following would result: which is illegal in DTD and W3C schema languages, since for a given member of model.global 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.

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 xsi:schemaLocation attribute) be supported where possible.

In order for the xsi:schemaLocation 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 per se. For DTDs this means adding to the list of attributes on the root element, which permits the non-namespace-aware DTD language to recognize the xsi:schemaLocation notation. For RELAX NG, the namespace and attribute would be declared in the usual way: and inside the root element declaration.

Note that declaration of the xsi:schemaLocation 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 trang), it may be necessary to perform that conversion prior to adding the xsi:schemaLocation declaration to the RELAX NG.

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.

When processing class, element, or macro specifications, there are three general rules: If a RELAX NG pattern or DTD parameter entity is being created, its name is the value of the corresponding ident attribute, prefixed by the value of any prefix attribute on schemaSpec. 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 tei_. Thus may generate a RELAX NG (compact syntax) pattern like this: References to these patterns (or, in DTDs, parameter entities) also need to be prefixed with the same value. If an element or attribute is being created, its default name is the value of the ident attribute, but if there is an altIdent child, its content is used instead. Where appropriate, the documentation strings in gloss and desc 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 xml:lang, a locale indication in the processing environment might be used to decide which to use. For example, heading en-tête encabezamiento titolo might generate a RELAX NG schema fragment like the following, if the locale is determined to be French: Alternatively, a selection might be made on the basis of the value of the version attribute which these elements carry as members of the att.translatable class.

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: when a pattern for an attribute class is created, it is named after the attribute class identifier (as above) suffixed by .attributes (e.g. att.editLike.attributes); when a pattern for an attribute is created, it is named after the attribute class identifier (as above) suffixed by .attribute. and then the identifier of the attribute (e.g. att.editLike.attribute.resp); when a parameterized schema is created, each element generates patterns for its attributes and its contents separately, suffixing respectively .attributes and .contents to the element name.

To create a RELAX NG schema, the processor processes every macroSpec, classSpec, and elementSpec 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.

A complete RELAX NG schema must have an rng:start element defining which elements can occur as the root of a document. The ODD schemaSpec has an optional start attribute, containing one or more patterns, which can be used to construct the rng:start. A pattern normally corresponds to an element name, but if a prefix (see above, ) is supplied for an element, the pattern consists of the prefix name with the element name.

Generation of DTDs largely follows the same pattern as RELAX NG generation, with one important exception—the order of declaration matters. 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: declare all model classes which have a predeclare value of true declare all macros which have a predeclare value of true declare all other classes declare the modules (if DTD fragments are being constructed) declare any remaining macros declare the elements and their attributes

Let us consider a complete example, a simple element with no attributes of its own: specifies the faith, religion, or belief set of a person. If DTD fragments are being generated (for use as described in ), this will result in the following: ]]]]> ]]> Here the whole stanza is contained in a marked section (for use as described in ), the element name is parameterized (see ), and the class attributes are entity references derived from the memberOf records in classes. Note the additional attribute which provides a default xmlns 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.

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: ]]> Here the attributes from classes have been expanded into individual entity references.

In Donald Knuth's literate programming terminology (), the previous sections have dealt with the tangle process; to generate documentation, we now turn to the weave process.

An ODD customization may consist largely of general documentation and examples, requiring no ODD-specific processing. It will normally however also contain a schemaSpec element and possibly some specGrp fragments.

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 .

Generating reference documentation for elementSpec, classSpec, and macroSpec 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.

One model of display on a web page is shown in , corresponding to the faith element shown in section .

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.