TEI TEIガイドラインP5: 22 ドキュメンテーション向け要素

22 ドキュメンテーション向け要素

Contents

This chapter describes a module which may be used for thedocumentation of the XML elements and element classes which make upany markup scheme, in particular that described by the TEI Guidelines,and also for the automatic generation of schemas or DTDs conforming tothat documentation. It should be used also by those wishing tocustomize or modify these Guidelines in a conformant manner, asfurther described in chapters 23.2 Personalization and Customization and 23.3 Conformance and may also be useful in the documentation of anyother comparable encoding scheme, even though it contains some aspectswhich are specific to the TEI and may not be generally applicable.

An overview of the kind of processing environment envisaged for themodule described by this chapter may be helpful. In the remainder ofthis chapter we refer to software which provides such a processingenvironment as an ODD processor. ⁸¹ Like any other piece of XML software,an ODD processor may be instantiated in many ways: the current systemuses a number of XSLT stylesheets which are freely available from theTEI, but this specification makes no particular assumptions about thetools which will be used to provide an ODD processing environment.

As the name suggests, an ODD processor uses a single XML documentto generate multiple outputs. These outputs will include:

formal reference documentation for elements, attributes, elementclasses, patterns etc. such as those provided in 付録 C Elements below;
detailed descriptive documentation, embedding some parts of theformal reference documentation, such as the tag description listsprovided 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 upan XML Document Type Declaration.

The input required to generate these outputs consists of runningprose, and special purpose elements documenting the components(elements, classes, etc.) which are to be declaredin the chosen schema language. All of this input is encoded in XMLusing the module defined by this chapter. In order to support morethan one schema language, this module uses a comparatively high levelmodel which can then be mapped by an ODD processor to the specificconstructs appropriate to the schema language in use. Although somemodern schema languages such as RELAX NG or W3Schema natively supportself-documentary features of this kind, we have chosen to retain theODD model, if only for reasons of compatibility with earlier versionsof these Guidelines. We do however use the ISO standard XML schemalanguage RELAX NG (http://www.relaxng.org) as a meansof declaring content models, rather than inventing a completely newXML-based representation for them.

In the TEI abstract model, a markup scheme (a schema)consists of a number of discrete modules, which can becombined more or less as required. Each major chapter of theseGuidelines defines a distinct module. Each module declares a number ofelements specific to that module, and may also populateparticular classes. All classes are declared globally;particular modules extend the meaning of a class by adding elements orattributes to it. Wherever possible, element content models aredefined in terms of classes rather than in terms of specificelements. Modules can also declare particular patterns,which act as short-cuts for commonly used content models or classreferences.

In the present chapter, we discuss the elements needed to supportthis system. In addition, section 22.1 Phrase Level DocumentaryElements discussessome general purpose elements which may be useful in any kind oftechnical documentation, wherever there is need to talk abouttechnical features of an XML encoding such as element names andattributes. Section 22.2 モジュールとスキーマ discusses the elementswhich are used to document XML modules and their highlevel components. Section 22.3 規格要素 discusses theelements which document XML elements and their attributes,element classes, and generic patterns or macros. Finally, section 22.7 タグ定義モジュール gives an overview of the whole module.

22.1 Phrase Level DocumentaryElementsTEI: Phrase Level DocumentaryElements¶

22.1.1 用語TEI: 用語¶

In any kind of technical documentation, the following phrase-levelelements may be found useful for marking up strings of text which needto be distinguished from the running text because they come from someformal language:

code contains literal code from some formal language such as aprogramming language.
lang (formal language) a name identifying the formal language in which the code is expressed
ident (identifier) contains an identifier or name for an object of some kind in a formal language.

Like other phrase-level elements used to indicate the semantics of atypographically distinct string, these are members of the model.emph class. They are available anywherethat running prose is permitted when the module defined by thischapter is included in a schema.

The code and ident elements areintended for use when citing brief passages in some formal language suchas a programming language, as in the following example:

If the variable <ident>z</ident> has a value of zero, a statement
such as <code>x=y/z</code> will usually cause a fatal error.

If the cited phrase is a mathematical or chemical formula, the morespecific formula element defined by the figures module (14.2 Formulae andMathematical Expressions) may bemore appropriate.

A further group of similar phrase-level elements is also definedfor the special case of representing parts of an XML document:

att (attribute) contains the name of an attribute appearing within running text.
gi (element name) contains the name (generic identifier) of an element.
tag contains text of a complete start- or end-tag, possiblyincluding attribute specifications, but excluding the opening andclosing markup delimiter characters.
val (value) contains a single attribute value.

These elements constitute the model.phrase.xml class, which is also a subclass of model.phrase. They are also available anywherethat running prose is permitted when the module defined by thischapter is included in a schema.

As an example of the recommended use of these elements, we quote froman imaginary TEI working paper:

The <gi>gi</gi> element is used to tag
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.

Within technical documentation, it is also often necessary toprovide more extended examples of usage or to present passages ofmarkup for discussion. The following special elements are provided forthese purposes:

eg (example) contains any kind of illustrative example.
egXML (example of XML) contains a single well-formed XML example demonstrating the use of some XML element or attribute, in which the egXML element itself functions as the root element.

Like the code element, the egXML element is usedto mark strings of formal code, or passages of XML markup. Theeg element may be used to enclose any kind of example, whichwill typically be rendered as a distinct block, possibly usingparticular formatting conventions, when the document is processed. Itis a specialised form of the more general q element providedby the TEI core module. In documents containing examples of XMLmarkup, the egXML element should be used for preference, asfurther discussed below in 22.4.2 例, since the content ofthis element can be checked for well-formedness.

These elements are members of the class att.xmlspace which provides the followingattribute:

att.xmlspace groups TEI elements for which it is reasonable to specify white space management using the W3C-defined xml:space attribute.
xml:space signals an intention that white space should be preserved by applications

These elements are added to the class model.egLike when this module is included in aschema. That class is a part of the general model.inter class, thus permitting eg oregXML elements to appear either within or betweenparagraph-like elements.

« 22.1.1 用語
Home | 目次

22.1.2 要素と属性TEI: 要素と属性¶

Within the body of a document using this module, the followingelements may be used to reference parts of the specification elementsdiscussed in section 22.3 規格要素, in particular thebrief prose descriptions these provide for elements and attributes.

specList (specification list) marks where a list of descriptions is to be inserted into the prose documentation.
specDesc/ (specification description) indicates that a description of the specified element or class should be included at this point within a document.

TEI practice requires that a specList listing the elementsunder discussion introduce each subsection of a module'sdocumentation. The source for the present section, for example, beginsas follows:

<div3>
<head>Element and attribute descriptions</head>
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>

TEI practice requires that a <gi>specList</gi> listing the elements
 ...


</div3>

When formatting the ptr element in this example, an ODDprocessor might simply generate the section number and title of thesection referred to, perhaps additionally inserting a link to thesection. In a similar way, when processing the specDescelements, an ODD processor must recover relevant details of theelements being specified (specList and specDesc inthis case) from their associated declaration elements: typically, thedetails recovered will include a brief description of the element andits attributes. These, and other data, will be stored in a specificationelement elsewhere within the current document, or they may be supplied by theODD processor in some other way, for example from a database. For thisreason, the link to the required specification element is always madeusing a TEI-defined key rather than an XML IDREF value. The ODDprocessor uses this key as a means of accessing the specificationelement required. There is no requirement that this be performed usingthe XML ID/IDREF mechanism, but there is an assumption that theidentifier be unique.

A specDesc generates in the documentation the identifier,and also the contents of the desc child of whateverspecification element is indicated by its key attribute,together with any associated attribute list, as in the exampleabove.

22.2 モジュールとスキーマTEI: モジュールとスキーマ¶

As mentioned above, the primary purpose of this module is to facilitatethe documentation of an XML schema derived from the TEI Guidelines. The following elements areprovided for this purpose:

schemaSpec (schema specification) generates a TEI-conformant schema and documentation for it.
moduleSpec (module specification) documents the structure, content, and purpose of a singlemodule, i.e. a named and externally visible group of declarations.
moduleRef (module reference) references a module which is to be incorporated into a schema.
specGrp (specification group) contains any convenient grouping of specifications for use within the current module.
specGrpRef/ (reference to a specification group) indicates that the declarations contained by the specGrp referenced should be inserted at this point.
attRef/ (attribute pointer) points to the definition of an attribute or group of attributes.

A module is a convenient way of grouping together elementand other declarations and associating an externally-visible name withthe group. A specification group performs essentially thesame function, but the resulting group is not accessible outside thescope of the ODD document in which it is defined, whereas a module canbe accessed by name from any TEI schema. Modules, elements, and theirattributes, element classes, and patterns are all individuallydocumented using further elements described in section 22.3 規格要素 below; part of that specification includes thename of a module to which the component belongs. An ODD processorgenerating XML DTD or schema fragments from a document marked upaccording to the recommendations of this chapter will generate suchfragments for each module element found. For example, thechapter documenting the TEI module for names and dates contains amodule specification like the following:

<moduleSpec xml:id="XDND" ident="namesdates">
<altIdent type="FPI">Names and Dates</altIdent>
<desc>Additional elements for names and dates</desc>
</moduleSpec>

together with specifications for all the elements, classes, andpatterns which make up that module, expressed usingelementSpec, classSpec, or patternSpecelements as appropriate. (These elements are discussed in section 22.3 規格要素 below) Each of those specifications carries amodule attribute, the value of which isnamesdates. An ODD processor encountering themoduleSpec element above can thus generate a schema fragmentfor the TEI namesdates module thatincludes declarations for all the elements (etc.) which referenceit.

In most realistic applications, it will be desirable to combinemore than one module together to form a complete schema.A schema consists of references to one or more modules orspecification groups, and may also contain explicit declarations orredeclarations of elements (see further 22.5 スキーマの作成). Anycombination of modules can be used to create a schema: the distinctionbetween base and additional tagsets in earlier versions of the TEIscheme has not been carried forward into P5.

A schema can combine references to TEI modules with references toother (non-TEI) modules using different namespaces, for example toinclude mathematical markup expressed using MathML in a TEIdocument. By default, the effect of combining modules is to allow allof the components declared by the constituent modules to coexist(where this is syntactically possible: where it is not — forexample, because of name clashes — a schema cannot begenerated). It is also possible to over-ride declarations contained bya module, as further discussed in section 22.5 スキーマの作成

It is often convenient to describe and operate on sets ofdeclarations smaller than the whole, and to document them in aspecific order: such collections are called specGrps(specification groups). Individual specGrp elements areidentified using the global xml:id attribute, and may then bereferenced from any point in an ODD document using thespecGrpRef element. This is useful if, for example, it isdesired to describe particular groups of elements in a specificsequence. Note however that the order in which element declarationsappear within the schema code generated from a moduleSpecelement cannot be altered, and is not affected by the order ofdeclarations within a specGrp.

An ODD processor will generate a piece of schema codecorresponding with the declarations contained by a specGrpelement in the documentation being output, and a cross reference tosuch a piece of schema code when processing a specGrpRef. Forexample, if the input text reads

This module contains three red elements:
<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>

then the output documentation will replace the two specGrpelements above with a representation of the schema code declaring theelements beetroot, east, and rose and thatdeclaring the elements sky and bayourespectively. Similarly, if the input text contains elsewhere apassage such as

<div>
<head>An overview of the imaginary module</head>
The imaginary module contains declarations for coloured things:
<specGrpRef target="#RED"/>
<specGrpRef target="#BLUE"/>

</div>

then the specGrpRef elements may be replaced by anappropriate piece of reference text such as ‘The RED elements weredeclared in section 4.2 above’, or even by a copy of the relevantdeclarations. As stated above, the order of declarations within theimaginary module described above will not be affected in anyway. Indeed, it is possible that the imaginary module will containdeclarations not present in any specification group, or that thespecification groups will refer to elements that come from differentmodules. Specification groups are always local to the document inwhich they are defined, and cannot be referenced externally (unlikemodules).

22.3 規格要素TEI: 規格要素¶

The following elements are used to specify elements, classes, andpatterns for inclusion in a given module:

elementSpec (element specification) documents the structure, content, and purpose of a singleelement type.
classSpec (class specification) contains reference information for a TEI element class; that is a group of elements which appear together in content models, or which share some common attribute, or both.
generate indicates which alternation and sequence instantiations of a model class may be referenced. By default, all variations are permitted.
macroSpec (macro specification) documents the function and implementation of a pattern.

Unlike most elements in the TEI scheme, each of these elements hasa fairly rigid internal structure consisting of a large number ofchild elements which are always presented in the same order. For thisreason, we refer to them informally as‘crystals’. Furthermore, since these elements alldescribe markup objects in broadly similar ways, they have severalchild elements in common. In the remainder of this section, we discussfirst 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 aspecGrp element, but the specification element for anyparticular component may only appear once (except in the case where amodification is being defined; see further 22.5 スキーマの作成). The order in which they appear will not affectthe order in which they are presented within any schema modulegenerated from the document. In documentation mode, however, an ODDprocessor will output the schema declarations corresponding with aspecification element at the point in the text where they areencountered, provided that they are contained by a specGrpelement, as discussed in the previous section. An ODD processor will alsoassociate all declarations found with the nominated module, thusincluding them within the schema code generated for that module, andit will also generate a full reference description for the objectconcerned in a catalogue of markup objects. These latter two actionsalways occur irrespective of whether or not the declaration isincluded in a specGrp.

22.4 共通要素TEI: 共通要素¶

This section discusses the child elements common to all of the specificationelements. These child elements are used to specify the naming, description,exemplification, and classification of the specification elements.

» 22.4.2 例
Home | 目次

22.4.1 解説TEI: 解説¶

remarks contains any commentary or discussion about the usage of anelement, attribute, class, or entity not otherwise documented within thecontaining element.
listRef (list of references) supplies a list of significant references to places where this element is discussed, in the current document or elsewhere.

A desc element is used to provide a briefcharacterization of the intended function of the element, class,value etc. being documented.

The remarks element contains any additionalcommentary about how the item concerned may be used, details ofimplementation-related issues, suggestions for other ways of treatingrelated information etc., as in the following example:

<elementSpec module="core" ident="foreign">

<remarks>
 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.
 The <gi>distinct</gi> element may be used to identify phrases
 belonging to sublanguages or registers not generally regarded as true
 languages.
</remarks>

</elementSpec>

A specification element will usually conclude with a list ofreferences, each tagged using the standard ptr element, andgrouped together into a listRef element: in the case of theforeign element discussed above, the list is as follows:

22.4.2 例TEI: 例¶

exemplum contains a single example demonstrating the use of an element, together with optional paragraphs of commentary.
eg (example) contains any kind of illustrative example.
egXML (example of XML) contains a single well-formed XML example demonstrating the use of some XML element or attribute, in which the egXML element itself functions as the root element.

The exemplum element is used to combine a singleillustrative example with an optional paragraph of commentaryfollowing or preceding it. The illustrative example itself may bemarked up using either the eg or the egXMLelement.

If an example contains XML markup, it should be marked up usingthe egXML element. In such a case, it will clearly be necessary todistinguish the markup within the example from themarkup of the document itself. In an XML schema environment, this iseasily done by using a different namespace for the egXML element. For example:

The <gi>term</gi> element may be used to mark any technical term, thus :<egXML xmlns="http://www.tei-c.org/ns/例"> This <term>recursion</term> is giving me a headache.</egXML>

Alternatively, the XML tagging within an example may be‘escaped’, either by using entityreferences, or by wrapping the whole example in a CDATA markedsection:

The <gi>term</gi> element may be used to mark any technical term, thus :<egXML xmlns="http://www.tei-c.org/ns/例"> This <term>recursion</term> is giving me a headache.</egXML>

or, equivalently:

The <gi>term</gi> element may be used to mark any technical term, thus :<egXML xmlns="http://www.tei-c.org/ns/例"><![CDATA[ This <term>recursion</term> is giving me a headache.]]></egXML>

If the XML contained in an example is not well-formed then it musteither be enclosed in a CDATA marked section, or‘escaped’ as above: this applies whether theeg or egXML is used. If it is well-formed but notvalid, then it should be enclosed in a CDATA marked section within anegXML.

An egXML element should not be used to tag non-XMLexamples: the general purpose eg or q elementsshould be used for such purposes.

22.4.3 分類TEI: 分類¶

In the TEI scheme elements are assigned to one or moreclasses, which may themselves have subclasses. Thefollowing elements are used to indicate class membership:

classes specifies all the classes of which the documented element orclass is a member or subclass.
memberOf specifies class membership of the parent element or class.
key specifies the identifier for a class of which the documented element or class is a member or subclass

The classes element appears within either theelementSpec or classSpec element. It specifies theclasses of which the element or class concerned is a member by meansof one or more memberOf child elements. Each such elementreferences a class by means of its key attribute. Classesthemselves are defined by the classSpec element described insection 22.4.6 要素クラス below.

For example, to show that the element gi is a member of the classmodel.phrase.xml, the elementSpec which documents thiselement contains the following classes element:

22.4.4 規定TEI: 規定¶

The elementSpec element is used to document an element type,together with its associated attributes. In addition to the elementslisted above, it may contain the following subcomponents:

content (content model) contains the text of a declaration for the schemadocumented.
attList contains documentation for all the attributes associated with thiselement, as a series of attDef elements.
org (organization) specifies whether all the attributes in the list are available (org="group") or only one of them (org="choice")

The content of the element content may beexpressed in one of two ways. It may use a schema language of somekind, as defined by a pattern calledmacro.schemaPattern, which is provided by themodule defined in thischapter. Alternatively, the legal content for an element may be fullyspecified using the valList element, described in 22.4.5 属性リスト below.

In the case of the TEIGuidelines, element content models are defined using RELAX NGpatterns, but the user may over-ride this by redefining thispattern.

Here is a very simple example

This content model uses the RELAX NG namespace, and will be copiedunchanged to the output when RELAX NG schemas are being generated. Whenan XML DTD is being generated, an equivalent declaration (in thiscase (#PCDATA)) will be output.

Here is a more complex example:

This is the content model for the teiHeader element,expressed in the RELAX NG syntax, which again is copied unchanged tothe output during schema generation. The equivalent DTD notationgenerated from this is (fileDesc, (%model.headerPart;)*,revisionDesc?).

The RELAX NG language does not formally distinguish element names,class names, or macro names: all names are patterns which are handledin the same way, as the above example shows. Within the TEI scheme,however, different naming conventions are used to distinguish amongstthe objects being named. Unqualified names (fileDesc,revisionDesc) are always element names. Names prefixedwith model. or att. (e.g. model.headerPart are always classnames. In DTD language, classes are represented by parameterentities (%model.headerPart; in the above example) See further1 TEIの基礎構造.

22.4.5 属性リストTEI: 属性リスト¶

The attList element is used to document information about acollection of attributes, either within an elementSpec, or within aclassSpec. An attribute list can be organized either as agroup of attribute definitions, all of which are understood to beavailable, or as a choice of attribute definitions, of which only oneis understood to be available. An attribute list may also containnested attribute lists.

The attDef element is used to document a single attribute, using an appropriateselection from the common elements already mentioned and thefollowing which are specific to attributes:

attDef (attribute definition) contains the definition of a single attribute.
usage specifies the optionality of an attribute or element.
datatype specifies the declared value for an attribute, by referring to any datatype defined by the chosen schema language.
defaultVal (default value) specifies the default declared value for an attribute.
valDesc (value description) specifies any semantic or syntactic constraint on the value thatan attribute may take, additional to the information carried by thedatatype element.
valList (value list) contains one or more valItem elements defining possible values for an attribute.
valItem documents a single attribute-value within a list of possible or mandatory items.

The attList within an elementSpec is used to specifyonly the attributes which are specific to that particularelement. Instances of the element may carry other attributes which aredeclared by the classes of which the element is a member. These extraattributes, which are shared by other elements, or by all elements,are specified by an attList contained within aclassSpec element, as described in section 22.4.6 要素クラス below.

» 22.4.5.2 値
Home | 目次

22.4.5.1 データ型TEI: データ型¶

The datatype element is used to state what kind of valuean attribute may have, using whatever facilities are provided by theunderlying schema language. For the TEI scheme, expressed inRELAX NG, elements from the RELAX NG namespace may be used, for example

permits any string of Unicode characters not containing markup, and isthus the equivalent of CDATA in DTD language.

The RELAX NG language also provides support for a number ofprimitive datatypes which may be specified here, using therng:data element: thus one may write

to specify that an element or attribute's contents should conform tothe W3C definition for Boolean.

Although only one child element may be given, this might be aselector such as rng:choice to indicate multiplepossibilities:

which would permit either a date or a real number. In fact, the childelement might be a rng:list element to indicate that asequence of values is required, a rng:param element tospecify a regular expression, or even a list of explicitrng:values. Such usages are permitted by the schemedocumented here, but are not recommended when it is desired to remainindependent of a particular schema language, since the full generalityof one schema language cannot readily be converted to that ofanother. In the TEI abstract model, datatyping should preferably becarried out either by explicit enumeration of permitted values (usingthe TEI-specific valList element described below), or bydefinition of an explicit pattern, using the TEI-specificmacroSpec element.

22.4.5.2 値TEI: 値¶

The valDesc element may be used to describe constraints on data content in an informal way: for example

<valDesc>must point to another <gi>align</gi>
element logically preceding this
one.</valDesc>

<valDesc>Values should be Library of Congress subject
headings.</valDesc>

<valDesc>A bookseller's surname,
taken from the list in <title>Pollard and Redgrave</title>
</valDesc>

As noted above, the datatype element is the firstconstraint on thepossible values for an attribute. The valDesc element can be used todescribe further constraints. For example, to specify that an attributeage can take positive integer values less than 100, thedatatype data.numeric might be used in combination witha valDesc such as ‘values must be positive integers lessthan 100’.

More usually, however, where constraints on values are explicitlyenumerated, the valList element is used, as in thefollowing example:

<valList type="closed">
<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>

Since this value list specifies that it is of type closed,only the values enumerated and glossed above are legal, and an ODDprocessor will typically enforce these constraints in the schemafragment generated.

The valList element is also used to provide illustrative examplesfor the values permitted and their significance, or to gloss themeaning of values implied by an attribute's datatype.

Note that the gloss element is needed to explain thesignificance of the identifier for an item only when this is notapparent, for example because it is abbreviated, as in the aboveexample. It should not be used to provide a full description of theintended meaning (this is the function of the desc element),nor to comment on equivalent values in other schemes (this is thepurpose of the equiv element).

« 22.4.5.2 値
Home | 目次

22.4.5.3 例TEI: 例¶

The following attList demonstrates some of thepossibilities; for more detailed examples, consult the tagged version ofthe reference material in these Guidelines.

<attList>
<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>
 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.
 </remarks>
</attDef>
</attList>

In the following example, the org attribute is used toindicate that instances of the element concerned may bear either a barattribute or a baz attribute, but not both. Thebax attribute is always available:

22.4.6 要素クラスTEI: 要素クラス¶

The element classSpec is used to document an elementclass or ‘class’, as defined in section 1.3 TEIのクラス. It has the following components, additional tothose already mentioned:

classSpec (class specification) contains reference information for a TEI element class; that is a group of elements which appear together in content models, or which share some common attribute, or both.
type indicates whether this is a model class or an attribute class
attList contains documentation for all the attributes associated with thiselement, as a series of attDef elements.

A class specification does not list all of its members. Instead,its members declare that they belong to it by means of aclasses element contained within the relevantelementSpec. This will contain a memberOf elementfor each class of which the relevant element is a member, supplyingthe name of the relevant class. For example, the elementSpecfor the element hi contains the following:

This indicates that the hi element is a member of the classwith identifier model.hiLike. TheclassSpec element that documents this class containsthe following declarations:

<classSpec type="model" ident="model.hiLike">
<desc>groups phrase-level elements related to highlighting that have
no specific semantics </desc>
<classes>
<memberOf key="model.highlighted"/>
</classes>
</classSpec>

which indicate that the class model.hiLikeis actually a member (or subclass) of the class model.highlighted.

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 elementcontained within the classSpec. In the case of model classes,no further information is neeeded to define the class beyond itsdescription, its identifier, and optionally any classes of which it isa member.

When a model class is referenced in the content model of an element(i.e. in the content of an elementSpec), its meaningwill depend on the name used to reference the class.

If the reference simply takes the form of the class name, it isinterpreted to mean an alternated list of all the current members ofthe class. For example, suppose that the members of the class model.hiLike are elements hi,it, and bo. Then a content model such as

would be equivalent to the explicit content model:

(or, to use RELAXNG compactsyntax, (hi|it|bo)*). However, a content modelreferencing the class as model.hiLike_sequence would beequivalent to the following explicit content model:

(or, in RELAXNG compact syntax,(hi,it,bo)*.

The following suffixes can be given to a class name when it isreferenced in a content model:

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 may be provided one or more times, in sequence

Thus a reference tomodel.hiLike_sequenceOptional in a content model would be equivalent to:

<rng:zeroOrMore>
<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>

, while a reference to model.hiLike_sequenceRepeatable would be equivalent to:

<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>

and a reference to model.hiLike_sequenceOptionalRepeatable would be equivalent to:

<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 classappear in a content model when one of the sequence options is used isthat in which the elements are declared.

In principal, all these possibilities are available to anyelement making reference to any class. The classSpec elementdefining the class may however limit the possibilities by means of itsgenerateOnly attribute, which can be used to saythat this particular model may only be referenced in acontent model with the suffixes it specifies. For example, if theclassSpec for model.hiLike tookthe form classSpec ident="model.hiLike" generateOnly="sequencesequenceOptional" then a content model referring to (say) model.hiLike_sequenceRepeatable would beregarded as invalid by an ODD processor.

When a classSpec contains an attList element, allthe members of that class inherit the attributes specified by it. Forexample, the class att.interpLike definesa small set of attributes common to all elements which are members ofthat class: those attributes are listed by the attListelement contained by the classSpec for att.interpLike. When processing the documentationelements for elements which are members of that class, an ODDprocessor is required to extend the attList (or equivalent)for such elements to include any attributes defined by theclassSpec elements concerned. There is a single globalattribute class, att.global.

« 22.4.6 要素クラス
Home | 目次

22.4.7 内容パタンTEI: 内容パタン¶

The macroSpec element is used to document patterns nototherwise documented by the elements described in this chapter. Itschief uses are to provide systematic documentation of the parameterentities used within TEI DTD fragments and to describe commoncontent models, but it may be used for any purpose. It has thefollowing components additional to those already introduced:

macroSpec (macro specification) documents the function and implementation of a pattern.
type indicates which type of entity should be generated, when an ODD processor is generating a module using XML DTD syntax.
remarks contains any commentary or discussion about the usage of anelement, attribute, class, or entity not otherwise documented within thecontaining element.
stringVal contains the intended expansion for the entity documentedby an patternSpec element, enclosed by quotation marks.

22.5 スキーマの作成TEI: スキーマの作成¶

The specification elements, and several of their children, are allmembers of the att.identified class, fromwhich they inherit the following attributes:

att.identified provides attributes for elements which can be referenced by means of a key attribute.

ident	Supplies the identifier by which this element is referenced.
predeclare	Says whether this object should be predeclared in the tei infrastructure module.
module	Supplies the name of the module in which this object is to be defined.
mode	specifies the effect of this declaration on its parent module.

These attributes are used by an ODD processor to determine howdeclarations are to be combined to form a schema or DTD, as furtherdiscussed in this section.

As noted above, a TEI schema is defined by a schemaSpecelement containing an arbitrary mixture of explicit declarations forobjects (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 majorpurpose of this mechanism is to simplify the process of defining usercustomizations, by providing a formal method for the user to combinenew declarations with existing ones, or to modify particular parts ofexisting declarations.

In the simplest case, a user-defined schema might simply combineall the declarations from two nominated modules:

An ODD processor, given such a document, would combine thedeclarations which belong to the named modules, and deliver the resultas a schema of the requested type. It might also generate documentation forall and only the elements declared by those modules.

A schema might also include declarations for new elements, as inthe following example:

A declaration for the elementsoundClip, which is not defined in the TEI scheme, will beadded to the output schema. This element will also be added to theexisting TEI class model.pPart.data, andwill thus be avilable in TEI conformant documents.

A schema might also include re-declarations of existing elements, asin the following example:

The effect of this is to redefine the content model for the elementhead as plain text, by over-riding the content childof the selected elementSpec. The attribute specificationmode="change" has the effect of over-riding only thosechildren elements of the elementSpec which appear both in theoriginal specification and in the new specification supplied above:content in this example. Note that if the value formode were replace, the effect would be toreplace all children elements of the original specification with the the children elements of the new specification, and thus (in thisexample) to delete all of them except content.

A schema may not contain more than two declarations for any givencomponent. The value of the mode attribute is used todetermine exactly how the second declaration (and its constituents)should be combined with the first. The following table summarizes howa processor should resolve duplicate declarations; the termidentifiable refers to those elements which can have amode attribute:

mode value	existing declaration	effect
add	no	add new declaration to schema; process its children in add mode
add	yes	raise error
replace	no	raise error
replace	yes	retain existing declaration; process new children in replacemode; 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 changeis provided
delete	no	raise error
delete	yes	ignore existing declaration and its children

22.6 Combining TEI and Non-TEIのモジュールTEI: Combining TEI and Non-TEIのモジュール¶

In the simplest case, all that is needed to include a non TEImodule in a schema is to reference its RELAXNG source using theurl attribute on moduleref. The following specification, for example, creates a schema in which declarationsfrom the non-TEI module svg11.rng (defining StandardVector Graphics) are included. To avoid any risk of name clashes, theschema specifies that all TEI patterns generated should be prefixed bythe string "TEI_".

This specification generates a single schema which might be used tovalidate either a TEI document (with the root element TEI),or an SVG document (with a root element svg), but wouldnot validate a TEI document containing svgelements. For that to be possible, the svg element mustbecome a member of a TEI model class (1.3 TEIのクラス), so thatit may be referenced by other TEI elements. To achieve this, we modifythe last moduleRef in the above example as follows:

This states that when the declarations from thesvg11.rng module are combined with those from the othermodules, the declaration for the model class model.graphicLike in the TEI moduleshould be extended to include the element svg as analternative. This has the effect that elements in the TEI schemewhich define their content model in terms of that element class(notably figure) can now include it. A RELAX NG schemagenerated from such a specification can be used to validate documentsin which the TEI figure element contains any valid SVGrepresentation of a graphic, embedded within an svg element.

22.7 タグ定義モジュールTEI: タグ定義モジュール¶

The module described in this chapter makes available the followingcomponents:

Module tagdocs: Documentation of TEI modules

Elements defined: altIdent att attDef attList attRef classSpec classes code content datatype defaultVal eg egXML elementSpec equiv exemplum gi ident listRef macroSpec memberOf moduleRef moduleSpec remarks schemaSpec specDesc specGrp specGrpRef specList stringVal tag val valDesc valItem valList
Classes defined: att.identified
TEIのマクロ defined: macro.schemaPattern

The selection and combination of modules to form a TEI schema is described in1.2 TEIスキーマの定義.

The elements described in this chapter are all members of one ofthree classes: model.oddDecl, model.oddRef, or model.phrase.xml, with the exceptions ofschemaSpec (a member of model.divPart)and both eg and egXML (members of model.common and model.egLike). All of these classes aredeclared along with the other general TEI classes, in the basicstructure module documented in 1 TEIの基礎構造.

In addition, some elements are members of theatt.identified class, which is documented in 22.5 スキーマの作成 above, and make use of themacro.schemapattern pattern, which is documented in 22.4.4 規定 above.

↑ Contents « 21 確信度・責任 » 23 TEIの使い方

注釈

81.

ODDis short for ‘One Document Does it all’, and was the nameinvented by the original TEI Editors for the predecessor of the systemcurrently used for this purpose. See further Burnard and Sperberg-McQueen (1995) and Burnard and Rahtz (2004).

↵