22 Documentation Elements
목차
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.2 Personalization and Customization and 23.3 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.7 Module for Documention Elements provides a summary overview of the elements provided by the module.
22.1 Phrase Level Documentary ElementsTEI: Phrase Level Documentary Elements¶
22.1.1 Phrase Level TermsTEI: Phrase Level Terms¶
- code 프로그래밍 언어와 같은 형식 언어의 문자적 부호를 포함한다.
lang (형식 언어) 부호가 표현된 형식 언어를 식별하는 이름 - ident (확인소) 형식 언어에서 어떤 종류의 개체에 대한 확인소 또는 이름을 포함한다.
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 (속성) 현 텍스트 내에 나타나는 속성명을 포함한다.
- gi (요소명) 요소의 이름(일반적 확인소)을 포함한다.
- tag 속성 명시를 포함하나 시작 및 종료 마크업 구분 문자를 제외한, 완전한 시작 또는 종료 태그의 텍스트를 포함한다.
- val (값) 단일 속성 값을 포함한다.
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 specialised 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.
The global xml:space is available to indicate that white space should be preserved within the content of these elements.
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 DescriptionsTEI: 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 SchemasTEI: Modules and Schemas¶
- schemaSpec (스키마 명시) TEI 구조 스키마 및 문서를 생성한다.
- moduleSpec (모듈 명시) 하나의 모듈에 대한 구조, 내용 및 목적을 기록한다. 즉, 선언의 이름과 외부적으로 가시적인 그룹
- moduleRef (모듈 참조) 하나의 스키마로 통합된 모듈을 참조한다.
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 (명시 그룹) 현 모듈 내에서 사용에 대한 명시를 다양한 방법의 그룹화를 포함한다.
- specGrpRef/ (명시 그룹에 대한 참조) 참조된 specGrp에 의해 포함된 선언은 이 지점에서 삽입되어야함을 나타낸다.
- attRef/ (속성 포인터) 속성 또는 속성의 그룹에 대한 정의를 가리킨다.
- 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 80
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 ElementsTEI: Specification Elements¶
- elementSpec (요소 명시) 단일 요소 유형의 구조, 내용 및 목적을 기록한다.
- classSpec (부류 명시) TEI 요소 부류에 대한 참조 정보를 포함한다; 이것은 내용 모델에서 함께 나타나거나, 공통 속성을 공유하거나, 이 둘을 포괄하는 요소들의 그룹이다.
generate 모델 부류의 교체 및 일련의 인스턴스 생성이 참조될 수 있음을 나타낸다. 기본적으로 모든 변이형이 허용된다. - macroSpec (매크로 명시) 유형의 기능 및 구현을 기록한다.
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 ElementsTEI: 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 ComponentsTEI: Description of Components¶
<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 ComponentsTEI: Exemplification of Components¶
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 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. If it is well-formed but not valid, then it should be enclosed in a CDATA marked section within an egXML.
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 ComponentsTEI: Classification of Components¶
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 SpecificationsTEI: Element Specifications¶
- content (내용 모델) 기록된 스키마에 대한 선언 텍스트를 포함한다.
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 일련의 attDef 요소로서, 이 요소와 연관된 모든 속성에 대한 기록을 포함한다.
org (조직) 목록의 모든 속성이 이용가능하거나(org="group") 그 중 하나만 이용가능한지를 명시한다.
22.4.4.1 Content modelsTEI: 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 RELAXNG
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 constraintsTEI: 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 SpecificationTEI: 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 (속성 정의) 단일 속성 정의를 포함한다.
usage 속성 또는 요소의 수의성을 명시한다. - datatype 선택된 스키마 언어에 의해 정의된 데이터 유형을 참조함으로써, 속성에 대한 선언된 값을 명시한다.
- defaultVal (기본 값) 속성에 대한 기본 선언 값을 명시한다.
- valDesc (값 기술) 데이터 유형 요소에 의해 수행된 정보와 더불어 속성이 취할 수 있는 값에 대한 의미적 또는 통사적 제약을 명시한다.
- valList (값 목록) 하나의 속성에 대한 가능한 값을 정의하는 하나 이상의 valItem 요소를 포함한다.
- valItem 가능한 또는 필수적 항목의 목록 내에서 단일 속성 값을 기록한다.
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 DatatypesTEI: 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 SpecificationTEI: 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’.
<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.
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 ExamplesTEI: 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 ClassesTEI: Element Classes¶
<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 principal, 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 DocumentationTEI: Pattern Documentation¶
- macroSpec (매크로 명시) 유형의 기능 및 구현을 기록한다.
type ODD 프로세서는 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 포함 요소 내에서 다르게 기록된 것이 없다면 요소, 속성, 부류 또는 개체의 사용 예에 관한 논평 또는 토론을 포함한다.
- stringVal macroSpec 요소에 의해 기록된 개체 에 대한 의도적 확장을 인용 부호의 표식을 통해서 제시한다.
22.5 Building a SchemaTEI: Building a Schema¶
- att.identified key 속성에 의해 참조될 수 있는 요소의 속성을 제시한다.
ident 이 요소가 참조된 확인소를 제공한다. predeclare tei 하부구조 모듈에서 이 대상이 미리 선언되어야 하는지를 설명한다. module 이 대상이 정의되어야 하는 모듈명을 제시한다.
- att.combinable provides attributes indicating how multiple references to
the same object in a schema should be combined
mode 그 부모 모듈에 이 선언의 효과를 명시한다.
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 tei:x.y.z
, where x.y.z
indicates the version number, e.g. tei:1.2.1
for 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="ptrGroup link"/>
</schemaSpec>
<moduleRef key="core" except="add del orig reg"/>
<elementRef key="ptrGroup"/>
<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 ModulesTEI: 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 Module for Documention ElementsTEI: Module for Documention Elements¶
- 모듈 tagdocs: Documentation of TEI modules
- 정의 요소: 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 stringVal tag val valDesc valItem valList
- 정의 부류: att.combinable att.identified
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.
↑ 내용 « 21 Certainty, Precision, and Responsibility » 23 Using the TEI