22 Documentation Elements
Contenu
This chapter describes a module which may be used for the documentation of the XML elements and element classes which make up any markup scheme, in particular that described by the TEI Guidelines, and also for the automatic generation of schemas or DTDs conforming to that documentation. It should be used also by those wishing to customize or modify these Guidelines in a conformant manner, as further described in chapters 23.3 Personalization and Customization and 23.4 Conformance and may also be useful in the documentation of any other comparable encoding scheme, even though it contains some aspects which are specific to the TEI and may not be generally applicable.
- formal reference documentation for elements, attributes, element classes, patterns, etc. such as those provided in Elements below;
- detailed descriptive documentation, embedding some parts of the formal reference documentation, such as the tag description lists provided in this and other chapters of these Guidelines;
- declarative code for one or more XML schema languages, specifically RELAX NG or W3C Schema.
- declarative code for fragments which can be assembled to make up an XML Document Type Declaration.
The input required to generate these outputs consists of running prose, and special purpose elements documenting the components (elements, classes, etc.) which are to be declared in the chosen schema language. All of this input is encoded in XML using elements defined in this chapter. In order to support more than one schema language, these elements constitute a comparatively high-level model which can then be mapped by an ODD processor to the specific constructs appropriate for the schema language in use. Although some modern schema languages such as RELAX NG or W3C Schema natively support self-documentary features of this kind, we have chosen to retain the ODD model, if only for reasons of compatibility with earlier versions of these Guidelines. We do however use the ISO standard XML schema language RELAX NG (http://www.relaxng.org) as a means of declaring content models, rather than inventing a completely new XML-based representation for them. We also use the ISO Schematron language to define additional constraints beyond those expressed in the content model, as further discussed in 22.4.4.2 Additional constraints below.
In the TEI system, a schema is built by combining element and attribute declarations, more or less as required. Each element is documented by an appropriate specification element and has an identifier unique across the whole TEI scheme. For convenience, these specifications are grouped into a number of discrete modules, which can also be combined more or less as required. Each major chapter of these Guidelines defines a distinct module. Each module declares a number of elements specific to that module, and may also populate particular classes. All classes are available globally, irrespective of the module in which they are declared; particular modules extend the meaning of a class by adding elements or attributes to it. Wherever possible, element content models are defined in terms of classes rather than in terms of specific elements. Modules can also declare particular patterns, which act as short-cuts for commonly used content models or class references.
In the present chapter, we discuss the elements needed to support this system. In addition, section 22.1 Phrase Level Documentary Elements discusses some general purpose elements which may be useful in any kind of technical documentation, wherever there is need to talk about technical features of an XML encoding such as element names and attributes. Section 22.2 Modules and Schemas discusses the elements which are used to document XML modules and their high-level components. Section 22.3 Specification Elements discusses the elements which document XML elements and their attributes, element classes, and generic patterns or macros. Finally, section 22.8 Module for Documention Elements provides a summary overview of the elements provided by the module.
22.1 Phrase Level Documentary Elements Phrase Level Documentary Elements¶
22.1.1 Phrase Level Terms Phrase Level Terms¶
- code contient un code littéral provenant d'un langage
formel, comme un langage de programmation.
lang (langage formel) nom identifiant le langage formel dans lequel le code est exprimé - ident (identifiant) contient un identifiant ou un nom dans un langage formel pour un objet quelconque.
such as <code>x=y/z</code> will usually cause a fatal error.</p>
If the cited phrase is a mathematical or chemical formula, the more specific formula element defined by the figures module (14.2 Formulæ and Mathematical Expressions) may be more appropriate.
- att (attribut) contient le nom d'un attribut apparaissant dans le courant du texte.
- gi (nom d'un élément) contient le nom (identifiant générique) d'un élément.
- tag (balise) le contenu d'une balise ouvrante ou fermante, avec éventuellement des spécifications d'attributs, mais à l'exclusion des caractères marquant l'ouverture et la fermeture de la balise.
- val (valeur) contient une seule valeur d'attribut.
element names when they appear in the text; the
<gi>tag</gi> element however is used to show how a tag as
such might appear. So one might talk of an occurrence of the
<gi>blort</gi> element which had been tagged
<tag>blort type='runcible'</tag>. The
<att>type</att> attribute may take any name token as
value; the default value is <val>spqr</val>, in memory of
its creator.</p>
Like the code element, the egXML element is used to mark strings of formal code, or passages of XML markup. The eg element may be used to enclose any kind of example, which will typically be rendered as a distinct block, possibly using particular formatting conventions, when the document is processed. It is a specialized form of the more general q element provided by the TEI core module. In documents containing examples of XML markup, the egXML element should be used for preference, as further discussed below in 22.4.2 Exemplification of Components, since the content of this element can be checked for well-formedness.
These elements are added to the class model.egLike when this module is included in a schema. That class is a part of the general model.inter class, thus permitting eg or egXML elements to appear either within or between paragraph-like elements.
22.1.2 Element and Attribute Descriptions Element and Attribute Descriptions¶
<head>Element and attribute descriptions</head>
<p>Within the body of a document using this module, the following
elements may be used to reference parts of the specification elements
discussed in section <ptr target="#TDcrystals"/>, in particular the
brief prose descriptions these provide for elements and attributes.
<specList>
<specDesc key="specList"/>
<specDesc key="specDesc"/>
</specList>
</p>
<p>TEI practice requires that a <gi>specList</gi> listing the elements
...
</p>
<!-- ... -->
</div3>
When formatting the ptr element in this example, an ODD processor might simply generate the section number and title of the section referred to, perhaps additionally inserting a link to the section. In a similar way, when processing the specDesc elements, an ODD processor must recover relevant details of the elements being specified (specList and specDesc in this case) from their associated declaration elements: typically, the details recovered will include a brief description of the element and its attributes. These, and other data, will be stored in a specification element elsewhere within the current document, or they may be supplied by the ODD processor in some other way, for example from a database. For this reason, the link to the required specification element is always made using a TEI-defined key rather than an XML IDREF value. The ODD processor uses this key as a means of accessing the specification element required. There is no requirement that this be performed using the XML ID/IDREF mechanism, but there is an assumption that the identifier be unique.
A specDesc generates in the documentation the identifier, and also the contents of the desc child of whatever specification element is indicated by its key attribute, as in the example above. Documentation for any attributes specified by the atts attribute will also be generated as an associated attribute list.
22.2 Modules and Schemas Modules and Schemas¶
- schemaSpec (spécification de schéma) génère un schéma conforme à la TEI et la documentation qui l'accompagne.
- moduleSpec (spécification de module) documente la structure, le contenu et les fonctions d'un module, i.e. d'un groupe de déclarations nommé et visible extérieurement.
- moduleRef (référence de module) référence un module qui doit être incorporé dans
un schéma.
include supplies a list of the elements which are to be copied from the specified module into the schema being defined. except supplies a list of the elements which are not to be copied from the specified module into the schema being defined. - specGrp (groupe de spécifications) contient tout regroupement approprié de spécifications pour une utilisation dans le module en question.
- specGrpRef/ (référence à un groupe de spécifications) indique que les déclarations contenues dans l'élément specGrpréférencé doivent être insérées à cet endroit.
- attRef/ (pointeur d'attribut) pointe vers la définition d'un attribut ou d'un groupe d'attributs.
- elementRef/ points to the specification for some element which is to be included in a schema
<altIdent type="FPI">Names and Dates</altIdent>
<desc>Additional elements for names and dates</desc>
</moduleSpec>
namesdates
. An ODD processor encountering the
moduleSpec element above can thus generate a schema fragment
for the TEI namesdates module that
includes declarations for all the elements (etc.) which reference it.In most realistic applications, it will be desirable to combine more than one module together to form a complete schema. A schema consists of references to one or more modules or specification groups, and may also contain explicit declarations or redeclarations of elements (see further 22.5 Building a Schema). Any combination of modules can be used to create a schema 85
A schema can combine references to TEI modules with references to other (non-TEI) modules using different namespaces, for example to include mathematical markup expressed using MathML in a TEI document. By default, the effect of combining modules is to allow all of the components declared by the constituent modules to coexist (where this is syntactically possible: where it is not—for example, because of name clashes—a schema cannot be generated). It is also possible to over-ride declarations contained by a module, as further discussed in section 22.5 Building a Schema
It is often convenient to describe and operate on sets of declarations smaller than the whole, and to document them in a specific order: such collections are called specGrps (specification groups). Individual specGrp elements are identified using the global xml:id attribute, and may then be referenced from any point in an ODD document using the specGrpRef element. This is useful if, for example, it is desired to describe particular groups of elements in a specific sequence. Note however that the order in which element declarations appear within the schema code generated from an ODD file element is not in general affected by the order of declarations within a specGrp.
<specGrp xml:id="RED">
<elementSpec ident="beetroot">
<!-- ... -->
</elementSpec>
<elementSpec ident="east">
<!-- ... -->
</elementSpec>
<elementSpec ident="rose">
<!-- ... -->
</elementSpec>
</specGrp>
and two blue ones:
<specGrp xml:id="BLUE">
<elementSpec ident="sky">
<!-- ... -->
</elementSpec>
<elementSpec ident="bayou">
<!-- ... -->
</elementSpec>
</specGrp>
</p>
<head>An overview of the imaginary module</head>
<p>The imaginary module contains declarations for coloured things:
<specGrpRef target="#RED"/>
<specGrpRef target="#BLUE"/>
</p>
</div>
22.3 Specification Elements Specification Elements¶
- elementSpec (spécification d'élément) documente la structure, le contenu et l'emploi d'un élément.
- classSpec (spécification de classe) contient des informations de référence pour une
classe d'éléments TEI, c'est-à-dire un groupe d'éléments qui figurent ensemble
dans des modèles de contenu ou qui partagent un attribut commun, ou qui ont l'un et l'autre.
generate donne les règles régissant dans une instance TEI l'ordre et l'alternance des éléments définis par la classe. Par défaut, toutes les variations sont données. - macroSpec (spécification de macro.) documente la fonction et l'implémentation d'un modèle.
Unlike most elements in the TEI scheme, each of these elements has a fairly rigid internal structure consisting of a large number of child elements which are always presented in the same order. For this reason, we refer to them metaphorically as ‘crystals’. Furthermore, since these elements all describe markup objects in broadly similar ways, they have several child elements in common. In the remainder of this chapter, we discuss first the elements which are common to all the specification elements, and then those which are specific to a particular type.
Specification elements may appear at any point in an ODD document, both between and within paragraphs as well as inside a specGrp element, but the specification element for any particular component may only appear once (except in the case where a modification is being defined; see further 22.5 Building a Schema). The order in which they appear will not affect the order in which they are presented within any schema module generated from the document. In documentation mode, however, an ODD processor will output the schema declarations corresponding with a specification element at the point in the text where they are encountered, provided that they are contained by a specGrp element, as discussed in the previous section. An ODD processor will also associate all declarations found with the nominated module, thus including them within the schema code generated for that module, and it will also generate a full reference description for the object concerned in a catalogue of markup objects. These latter two actions always occur irrespective of whether or not the declaration is included in a specGrp.
22.4 Common Elements Common Elements¶
This section discusses the child elements common to all of the specification elements. These child elements are used to specify the naming, description, exemplification, and classification of the specification elements.
22.4.1 Description of Components Description of Components¶
- remarks (remarques) contient tout commentaire sur l'utilisation d'un élément, d'un attribut, d'une classe ou d'une entité qui n'est pas documentée ailleurs à l'intérieur de l'élément conteneur.
- listRef (liste de références) fournit une liste de références signifiantes là où cet élément est commenté, dans le document courant ou ailleurs.
<desc>Name of an actor appearing within a cast list.</desc>
<desc xml:lang="ja"> 登場人物リスト中にある役者名を示す.</desc>
<desc xml:lang="it">nome di un attore che appare nella lista dei personaggi.</desc>
<!-- ... -->
</elementSpec>
<!--... -->
<remarks>
<p>This element is intended for use only where no other element
is available to mark the phrase or words concerned. The global
<att>xml:lang</att> attribute should be used in preference to this element
where it is intended to mark the language of the whole of some text
element.</p>
<p>The <gi>distinct</gi> element may be used to identify phrases
belonging to sublanguages or registers not generally regarded as true
languages.</p>
</remarks>
<!--... -->
</elementSpec>
<ptr target="#COHQHF"/>
</listRef>
22.4.2 Exemplification of Components Exemplification of Components¶
- exemplum (exemple) contient un exemple qui montre l'utilisation d'un élément avec de possibles paragraphes de commentaires.
- eg (exemple) contient toutes sortes d'exemples illustratifs.
- egXML (exemple en XML) contient un seul exemple en XML bien formé montrant
l'utilisation d'un élément ou d'un attribut XML.
valid indicates the intended validity of the example with respect to a schema.
The exemplum element is used to combine a single illustrative example with an optional paragraph of commentary following or preceding it. The illustrative example itself may be marked up using either the eg or the egXML element.
If complex rendition information is required, then the rendition attribute, in the TEI namespace, can be used.
If the XML contained in an example is not well-formed then it must either be enclosed in a CDATA marked section, or ‘escaped’ as above: this applies whether the eg or egXML is used. The valid attribute on egXML may be used to indicate the XML validity of the example with respect to some schema, as being valid, invalid, or feasibly valid.
An egXML element should not be used to tag non-XML examples: the general purpose eg or q elements should be used for such purposes.
22.4.3 Classification of Components Classification of Components¶
- classes (classes) précise toutes les classes dont la classe ou l'élément documentés est un membre ou une sous-classe.
- memberOf précise à quelle classe appartiennent la classe ou
l'élément parent.
key précise l’identifiant pour une classe pour laquelle l'élément documenté ou classe est un membre ou sous-classe.
The classes element appears within either the elementSpec or classSpec element. It specifies the classes of which the element or class concerned is a member by means of one or more memberOf child elements. Each such element references a class by means of its key attribute. Classes themselves are defined by the classSpec element described in section 22.4.6 Element Classes below.
<memberOf key="model.phrase.xml"/>
</classes>
22.4.4 Element Specifications Element Specifications¶
- content (modèle de contenu) contient la déclaration d'un modèle de contenu
pour le schéma documenté.
autoPrefix controls whether or not pattern names generated in the corresponding RELAXNG schema source are automatically prefixed to avoid potential nameclashes. - constraint (constraint rules) the formal rules of a constraint
- attList (liste d'attributs) contient la documentation pour tous les attributs
associés à cet élément comme une série d'éléments attDef.
org (conditions d'utilisation) précise si les attributs dans la liste sont tous disponibles (org="group") ou seulement l'un d'entre eux (org="choice").
22.4.4.1 Content models Content models¶
The content of the element content may be
expressed in one of two ways. It may use a schema language of some
kind, as defined by a pattern called
macro.schemaPattern
, which is provided by the
module defined in this
chapter. Alternatively, the legal content for an element may be fully
specified using the valList element, described in 22.4.5 Attribute List Specification below.
In the case of the TEI
Guidelines, element content models are defined using RELAX NG
patterns, although the user may over-ride this by redefining the
macro.schemaPattern
pattern.
<rng:text/>
</content>
text
, using the RELAX NG namespace. This model will
be copied unchanged to the output when RELAX NG schemas are being
generated. When an XML DTD is being generated, an equivalent
declaration (in this case (#PCDATA)
) will be output.<rng:group>
<rng:ref name="fileDesc"/>
<rng:zeroOrMore>
<rng:ref name="model.teiHeaderPart"/>
</rng:zeroOrMore>
<rng:optional>
<rng:ref name="revisionDesc"/>
</rng:optional>
</rng:group>
</content>
(fileDesc, (%model.teiHeaderPart;)*,
revisionDesc?)
.
The RELAX NG language does not formally distinguish element names,
attribute names, class names, or macro names: all names are patterns
which are handled in the same way, as the above example shows. Within
the TEI scheme, however, different naming conventions are used to
distinguish amongst the objects being named. Unqualified names
(fileDesc
, revisionDesc
) are always element
names. Names prefixed with model.
or att.
(e.g. model.teiHeaderPart and att.typed)
are always class
names. In DTD language, classes are represented by parameter entities
(%model.teiHeaderPart;
in the above example); see further
1 The TEI Infrastructure.
TEI_ident
rather than simply ident
. Most of the time, this
behaviour is entirely transparent to the user; the one occasion when
it is not will be where a content model (expressed using RELAX NG
syntax) needs explicitly to reference either the TEI ident or
the other one. In such a situation, the autoPrefix
attribute on content may be used. For example, suppose that
we wish to define a content model for term which permits
either a TEI ident or the ident defined by some
other vocabulary. A suitable content model would be generated from
the following content element:
<rng:choice>
<rng:ref name="TEI_ident"/>
<rng:ref name="ident"/>
</rng:choice>
</content>
22.4.4.2 Additional constraints Additional constraints¶
In addition to the content element, a set of identified general constraint elements can be provided where rules about the validity of an element can be expressed. They are identifiable in order that a TEI customization may override, delete or change them individually. These elements follow the content element, are permitted as siblings of datatype in attDef, and as children of schemaSpec. The constraints can be expressed in any notation which is found useful; the scheme must be recorded using the scheme attribute of constraint.
The TEI Guidelines themselves provide constraints using the ISO Schematron language. These are normative, and changes to them may affect conformance, just as for content. Although not all processors will be able to process all constraints, they should follow as many as they can.
A complete Schematron document consists of a <schema> element containing <ns> and <pattern> elements; each pattern specifies a rule and a context. In a normal TEI specification it is expected that <ns> and <pattern> elements will be placed wherever suitable for documentation, and extracted into a single Schematron schema, or embedded in another schema language. As a convenience for readers, however, TEI processors should also support the direct placement of Schematron <report> and <assert> elements inside the constraint element within elementSpec; the <pattern> and <rule> containers should then be generated automatically.
<desc>Check mutually incompatible attributes</desc>
<constraint>
<sch:report test="@active and @mutual">Only one of the attributes
'active' and 'mutual' may be supplied</sch:report>
<sch:report test="@passive and not(@active)">the attribute 'passive'
may be supplied only if the attribute 'active' is
supplied</sch:report>
</constraint>
</constraintSpec>
<constraint>
<sch:ns prefix="tei" uri="http://www.tei-c.org/ns/1.0"/>
<sch:pattern id="Alt tags">
<sch:rule context="tei:figure">
<sch:report test="not(tei:figDesc or tei:head)"> You should
provide information in a figure from which
we can construct an alt attribute in HTML </sch:report></sch:rule></sch:pattern>
</constraint>
</constraintSpec>
<constraint>
<sch:ns prefix="tei" uri="http://www.tei-c.org/ns/1.0"/>
<sch:pattern id="Tables">
<sch:rule context="tei:table">
<sch:assert test="tei:head">A <table> should have a caption, using a <head> element</sch:assert>
<sch:report test="parent::tei:body">Do not use tables to lay out the document body</sch:report></sch:rule></sch:pattern>
</constraint>
</constraintSpec>
<constraint>
<sch:rule context="tei:div">
<sch:assert test="not(tei:div) or count(tei:div)>1">a division must contain
at least two subdivisions</sch:assert></sch:rule>
</constraint>
</constraintSpec>
<constraint>
<sch:assert
test="tei:fileDesc/tei:titleStmt/tei:title[@type='introductory']"> an introductory component of the title is expected
</sch:assert>
</constraint>
</constraintSpec>
<constraintSpec ident="maintitle" scheme="isoschematron">
<constraint>
<sch:assert
test="tei:fileDesc/tei:titleStmt/tei:title[@type='main']"> a main title must be supplied
</sch:assert>
</constraint>
</constraintSpec>
22.4.5 Attribute List Specification Attribute List Specification¶
The attList element is used to document information about a collection of attributes, either within an elementSpec, or within a classSpec. An attribute list can be organized either as a group of attribute definitions, all of which are understood to be available, or as a choice of attribute definitions, of which only one is understood to be available. An attribute list may also contain nested attribute lists.
- attDef (définition d'attribut) contient la définition d'un attribut.
usage précise qu'un attribut ou un élément sont facultatifs. - datatype (type de données) précise la valeur déclarée d'un attribut en faisant référence à un type de données défini dans le langage choisi pour le schéma.
- defaultVal (valeur par défaut) précise la valeur déclarée par défaut pour un attribut.
- valDesc (description de la valeur) précise toute contrainte sémantique ou syntaxique sur la valeur que peut prendre un attribut, en supplément de l'information portée par l'élément datatype.
- valList (liste de valeurs) contient un ou plusieurs éléments valItem qui définissent des valeurs possibles pour un attribut.
- valItem documente une valeur d'attribut unique dans une liste d'items possibles ou obligatoires
The attList within an elementSpec is used to specify only the attributes which are specific to that particular element. Instances of the element may carry other attributes which are declared by the classes of which the element is a member. These extra attributes, which are shared by other elements, or by all elements, are specified by an attList contained within a classSpec element, as described in section 22.4.6 Element Classes below.
22.4.5.1 Datatypes Datatypes¶
<rng:text/>
</datatype>
CDATA
in DTD language.
<rng:data type="boolean"/>
</datatype>
boolean
.<rng:choice>
<rng:data type="Date"/>
<rng:data type="Float"/>
</rng:choice>
</datatype>
rng:list
element to indicate that a
sequence of values is required, a rng:param
element to
specify a regular expression, or even a list of explicit
rng:value
s. Such usages are permitted by the scheme
documented here, but are not recommended when it is desired to remain
independent of a particular schema language, since the full generality
of one schema language cannot readily be converted to that of
another. In the TEI abstract model, datatyping should preferably be
carried out either by explicit enumeration of permitted values (using
the TEI-specific valList element described below), or by
definition of an explicit pattern, using the TEI-specific
macroSpec element discussed further in section 22.4.7 Pattern Documentation.22.4.5.2 Value Specification Value Specification¶
element logically preceding this
one.</valDesc>
headings.</valDesc>
taken from the list in <title>Pollard and Redgrave</title>
</valDesc>
As noted above, the datatype element constrains the possible values for an attribute. The valDesc element can be used to describe further constraints. For example, to specify that an attribute age can take positive integer values less than 100, the datatype data.numeric might be used in combination with a valDesc such as ‘values must be positive integers less than 100’. Constraints expressed in this way are purely documentary ; to enforce them, the constraintSpec element described in section 22.4.4 Element Specifications must be used.
<valItem ident="req">
<gloss>required</gloss>
</valItem>
<valItem ident="mwa">
<gloss>mandatory when applicable</gloss>
</valItem>
<valItem ident="rec">
<gloss>recommended</gloss>
</valItem>
<valItem ident="rwa">
<gloss>recommended when applicable</gloss>
</valItem>
<valItem ident="opt">
<gloss>optional</gloss>
</valItem>
</valList>
The valList element is also used to provide illustrative examples of the kinds of values expected. In such cases the type attribute will have the value open and the datatype will usually be data.enumerated.
The valList element may also be used (as a child of the content element) to put constraints on the permitted content of an element, as noted at 22.4.4.1 Content models. This use is not however supported by all schema languages, and is therefore not recommended if support for non-RELAXNG systems is a consideration.
Note that the gloss element is needed to explain the significance of the identifier for an item only when this is not apparent, for example because it is abbreviated, as in the above example. It should not be used to provide a full description of the intended meaning (this is the function of the desc element), nor to comment on equivalent values in other schemes (this is the purpose of the equiv element), nor to provide alternative versions of the ident attribute value in other languages (this is the purpose of the altIdent element).
22.4.5.3 Examples Examples¶
<attDef ident="type">
<desc>describes the form of the list.</desc>
<datatype>
<rng:text/>
</datatype>
<defaultVal>simple</defaultVal>
<valList type="semi">
<valItem ident="ordered">
<desc>list items are numbered or lettered. </desc>
</valItem>
<valItem ident="bulleted">
<desc>list items are marked with a bullet or other
typographic device. </desc>
</valItem>
<valItem ident="simple">
<desc>list items are not numbered or bulleted.</desc>
</valItem>
<valItem ident="gloss">
<desc>each list item glosses some term or
concept, which is given by a label element preceding
the list item.</desc>
</valItem>
</valList>
<remarks>
<p>The formal syntax of the element declarations allows
<gi>label</gi> tags to be omitted from lists tagged <tag>list
type="gloss"</tag>; this is however a semantic error.</p>
</remarks>
</attDef>
</attList>
<attDef ident="bax">
<!-- ... -->
</attDef>
<attList org="choice">
<attDef ident="bar">
<!-- ... -->
</attDef>
<attDef ident="baz">
<!-- ... -->
</attDef>
</attList>
</attList>
22.4.6 Element Classes Element Classes¶
- classSpec (spécification de classe) contient des informations de référence pour une
classe d'éléments TEI, c'est-à-dire un groupe d'éléments qui figurent ensemble
dans des modèles de contenu ou qui partagent un attribut commun, ou qui ont l'un et l'autre.
type indique si c'est une classe de modèles ou une classe d'attributs - classRef/ points to the specification for an attribute or model class which is to be included in a schema
- attList (liste d'attributs) contient la documentation pour tous les attributs associés à cet élément comme une série d'éléments attDef.
<memberOf key="model.hiLike"/>
</classes>
<desc>groups phrase-level elements related to highlighting that have
no specific semantics </desc>
<classes>
<memberOf key="model.highlighted"/>
</classes>
</classSpec>
The function of a model class declaration is to provide another way of referring to a group of elements. It does not confer any other properties on the elements which constitute its membership.
The attribute type is used to distinguish between ‘model’ and ‘attribute’ classes. In the case of attribute classes, the attributes provided by membership in the class are documented by an attList element contained within the classSpec. In the case of model classes, no further information is needed to define the class beyond its description, its identifier, and optionally any classes of which it is a member.
When a model class is referenced in the content model of an element (i.e. in the content of an elementSpec), its meaning will depend on the name used to reference the class.
<rng:zeroOrMore>
<rng:ref name="model.hiLike"/>
</rng:zeroOrMore>
</content>
<rng:zeroOrMore>
<rng:choice>
<rng:ref name="hi"/>
<rng:ref name="it"/>
<rng:ref name="bo"/>
</rng:choice>
</rng:zeroOrMore>
</content>
(hi|it|bo)*
). However, a content model
referencing the class as model.hiLike_sequence would be
equivalent to the following explicit content model: <rng:zeroOrMore>
<rng:ref name="hi"/>
<rng:ref name="it"/>
<rng:ref name="bo"/>
</rng:zeroOrMore>
</content>
(hi,it,bo)*
). - alternation
- members of the class are alternatives
- sequence
- members of the class are to be provided in sequence
- sequenceOptional
- members of the class may be provided, in sequence, but are optional
- sequenceOptionalRepeatable
- members of the class may be provided one or more times, in sequence, but are optional
- sequenceRepeatable
- members of the class must be provided one or more times, in sequence
<rng:optional>
<rng:ref name="hi"/>
</rng:optional>
<rng:optional>
<rng:ref name="it"/>
</rng:optional>
<rng:optional>
<rng:ref name="bo"/>
</rng:optional>
</rng:zeroOrMore>
<rng:oneOrMore>
<rng:ref name="hi"/>
</rng:oneOrMore>
<rng:oneOrMore>
<rng:ref name="it"/>
</rng:oneOrMore>
<rng:oneOrMore>
<rng:ref name="bo"/>
</rng:oneOrMore>
</rng:zeroOrMore>
<rng:zeroOrMore>
<rng:ref name="hi"/>
</rng:zeroOrMore>
<rng:zeroOrMore>
<rng:ref name="it"/>
</rng:zeroOrMore>
<rng:zeroOrMore>
<rng:ref name="bo"/>
</rng:zeroOrMore>
</rng:zeroOrMore>
The ‘sequence’ in which members of a class appear in a content model when one of the sequence options is used is that in which the elements are declared.
In principle, all these possibilities are available to any element making reference to any class. The classSpec element defining the class may however limit the possibilities by means of its generate attribute, which can be used to say that this particular model may only be referenced in a content model with the suffixes it specifies. For example, if the classSpec for model.hiLike took the form <classSpec ident="model.hiLike" generate="sequence sequenceOptional"> then a content model referring to (say) model.hiLike_sequenceRepeatable would be regarded as invalid by an ODD processor.
An attribute class (a classSpec of type atts) contains an attList element which lists the attributes that all the members of that class inherit from it. For example, the class att.interpLike defines a small set of attributes common to all elements which are members of that class: those attributes are listed by the attList element contained by the classSpec for att.interpLike. When processing the documentation elements for elements which are members of that class, an ODD processor is required to extend the attList (or equivalent) for such elements to include any attributes defined by the classSpec elements concerned. There is a single global attribute class, att.global, to which some modules contribute additional attributes when they are included in a schema.
22.4.7 Pattern Documentation Pattern Documentation¶
- macroSpec (spécification de macro.) documente la fonction et l'implémentation d'un
modèle.
type indique quel type d'entité doit être généré lorsqu'un processeur "ODD" génère un module TEI qui utilise la syntaxe XML DTD. - macroRef/ points to the specification for some pattern which is to be included in a schema
key the identifier used for the required pattern within the source indicated. - remarks (remarques) contient tout commentaire sur l'utilisation d'un élément, d'un attribut, d'une classe ou d'une entité qui n'est pas documentée ailleurs à l'intérieur de l'élément conteneur.
22.5 Building a Schema Building a Schema¶
- att.identified fournit les attributs pour des éléments référençables au moyen d'un
attribut key.
ident fournit l'identifiant qui référence cet élément. predeclare précise si cet objet nécessite une prédéfinition dans le module d'infrastructure tei. module fournit le nom du module dans lequel doit être défini cet objet.
- att.combinable provides attributes indicating how multiple references to
the same object in a schema should be combined
mode précise l'effet de cette déclaration sur son parent.
- att.namespaceable provides an attribute indicating the target namespace for an object being created
These attributes are used by an ODD processor to determine how declarations are to be combined to form a schema or DTD, as further discussed in this section.
As noted above, a TEI schema is defined by a schemaSpec element containing an arbitrary mixture of explicit declarations for objects (i.e. elements, classes, patterns, or macro specifications) and references to other objects containing such declarations (i.e. references to specification groups, or to modules). A major purpose of this mechanism is to simplify the process of defining user customizations, by providing a formal method for the user to combine new declarations with existing ones, or to modify particular parts of existing declarations.
<moduleRef key="core"/>
<moduleRef key="linking"/>
</schemaSpec>
The value specified for the source attribute, when it is
supplied as a URL, specifies any convenient location from which the
relevant ODD files may be obtained. For the current release of the TEI
Guidelines, a URL in the form
http://www.tei-c.org/Vault/P5/x.y.z/xml/tei/odd/p5subset.xml
may be used, where x.y.z
represents the version number,
e.g. 1.3.0
. Alternatively, if the ODD files are locally
installed, it may be more convenient to supply a value such as
../ODDs/p5subset.xml".
The value for the source attribute may any form of URI. A set of TEI-conformant specifications in a form directly usable by an ODD processor must be available at the location indicated. When no source value is supplied, an ODD processor may either raise an error or assume that the location of the current release of the TEI Guidelines is intended.
If the source is specified in the form of a private URI, the form
recommended is aaa:x.y.z
, where aaa
is a
prefix indicating the markup language in use, and x.y.z
indicates the version number. For example, tei:1.2.1
should be used to reference release
1.2.1 of the current TEI Guidelines. When such a URI is used, it will
usually be necessary to translate it before such a file can be used
in blind interchange.
<moduleRef key="core" except="add del orig reg"/>
<moduleRef key="linking" include="linkGroup link"/>
</schemaSpec>
<moduleRef key="core" except="add del orig reg"/>
<elementRef key="linkGroup"/>
<elementRef key="link"/>
</schemaSpec>
<moduleRef key="teiheader"/>
<moduleRef key="verse"/>
<elementSpec ident="soundClip">
<classes>
<memberOf key="model.pPart.data"/>
</classes>
</elementSpec>
</schemaSpec>
<moduleRef key="teiheader"/>
<moduleRef key="teistructure"/>
<elementSpec ident="head" mode="change">
<content>
<rng:ref name="macro.xtext"/>
</content>
</elementSpec>
</schemaSpec>
mode="change"
has the effect of over-riding only those
children elements of the elementSpec which appear both in the
original specification and in the new specification supplied above:
content in this example. Note that if the value for
mode were replace, the effect would be to
replace all children elements of the original specification with the
the children elements of the new specification, and thus (in this
example) to delete all of them except content. mode value | existing declaration | effect |
add | no | add new declaration to schema; process its children in add mode |
add | yes | raise error |
replace | no | raise error |
replace | yes | retain existing declaration; process new children in replace mode; ignore existing children |
change | no | raise error |
change | yes | process identifiable children according to their modes; process unidentifiable children in replace mode; retain existing children where no replacement or change is provided |
delete | no | raise error |
delete | yes | ignore existing declaration and its children |
22.6 Combining TEI and Non-TEI Modules Combining TEI and Non-TEI Modules¶
<moduleRef key="header"/>
<moduleRef key="core"/>
<moduleRef key="tei"/>
<moduleRef key="textstructure"/>
<moduleRef url="svg11.rng"/>
</schemaSpec>
<content>
<rng:define name="TEI_model.graphicLike" combine="choice">
<rng:ref name="svg"/>
</rng:define>
</content>
</moduleRef>
This states that when the declarations from the svg11.rng module are combined with those from the other modules, the declaration for the model class model.graphicLike in the TEI module should be extended to include the element <svg:svg> as an alternative. This has the effect that elements in the TEI scheme which define their content model in terms of that element class (notably figure) can now include it. A RELAX NG schema generated from such a specification can be used to validate documents in which the TEI figure element contains any valid SVG representation of a graphic, embedded within an <svg:svg> element.
22.7 Linking Schemas to XML Documents Linking Schemas to XML Documents¶
22.8 Module for Documention Elements Module for Documention Elements¶
- Module tagdocs: Éléments de déclaration d’un modèle
- Eléments définis: altIdent att attDef attList attRef classRef classSpec classes code constraint constraintSpec content datatype defaultVal eg egXML elementRef elementSpec equiv exemplum gi ident listRef macroRef macroSpec memberOf moduleRef moduleSpec remarks schemaSpec specDesc specGrp specGrpRef specList tag val valDesc valItem valList
- Classes définies: att.combinable att.identified att.namespaceable
- Macros définies: macro.anyXML macro.schemaPattern
The elements described in this chapter are all members of one of three classes: model.oddDecl, model.oddRef, or model.phrase.xml, with the exceptions of schemaSpec (a member of model.divPart) and both eg and egXML (members of model.common and model.egLike). All of these classes are declared along with the other general TEI classes, in the basic structure module documented in 1 The TEI Infrastructure.
In addition, some elements are members of the
att.identified class, which is documented in 22.5 Building a Schema above, and make use of the
macro.schemaPattern
pattern, which is documented in 22.4.4 Element Specifications above.