| Previous | Up | Next |
This chapter describes an auxiliary DTD which may be used for the documentation of new elements, element classes and entities. It is primarily intended for use by those wishing to extend or modify the content of these Guidelines in a conformant manner, as described in chapters 29 and 28 ; it may however be of use for the documentation of any SGML or SGML-like encoding scheme. The elements described here are those used to document the TEI scheme itself, in part VII of the current document.
Three distinct elements are used to document a tag set, the contents of each of which is described in more detail in the appropriate section of this chapter.
In addition to these documentary elements, the following phrase-level elements may be found useful for marking up occurrences of element names etc. within the body of running text.
As an example of the recommended use of these elements, we quote from an imaginary TEI working paper:
<p>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.
These elements and their components make up the auxiliary DTD for tag documentation, which is contained in the file teitsd2.dtd . This file has the following overall structure:
<!-- 27: File teitsd2.dtd: Auxiliary DTD for Tag Set -->
<!-- Documentation -->
<!-- Text Encoding Initiative: Guidelines for Electronic -->
<!-- Text Encoding and Interchange. Document TEI P3, 1994. -->
<!-- Copyright (c) 1994 ACH, ACL, ALLC. Permission to copy -->
<!-- in any form is granted, provided this notice is -->
<!-- included in all copies. -->
<!-- These materials may not be altered; modifications to -->
<!-- these DTDs should be performed as specified in the -->
<!-- Guidelines in chapter "Modifying the TEI DTD." -->
<!-- These materials subject to revision. Current versions -->
<!-- are available from the Text Encoding Initiative. -->
<!-- Embed entities for TEI generic identifiers. -->
<!ENTITY % TEI.elementNames system 'teigis2.ent' >
%TEI.elementNames;
<!-- Define entities for TEI keywords. -->
<!ENTITY % TEI.keywords.ent system 'teikey2.ent' >
%TEI.keywords.ent;
<!-- Define element classes for content models, shared -->
<!-- attributes for element classes, and global attributes. -->
<!-- (This all happens within the file TEIclas2.ent.) -->
<!ENTITY % TEI.elementClasses system 'teiclas2.ent' >
%TEI.elementClasses;
<!-- Embed the core tag set -->
<!ENTITY % TEI.core.dtd system 'teicore2.dtd' >
%TEI.core.dtd;
<!-- Define the top-level element for this DTD -->
<!ELEMENT tsd - O ((tagDoc | entDoc | classDoc)+) >
<!ATTLIST tsd %a.global; >
<!-- Define some additions for the phrase level tags -->
<!ELEMENT gi - O (#PCDATA) >
<!ATTLIST gi %a.global;
TEI (yes | no) yes >
<!ELEMENT tag - - (#PCDATA) >
<!ATTLIST tag %a.global;
TEI (yes | no) yes >
<!ELEMENT att - - (#PCDATA) >
<!ATTLIST att %a.global;
TEI (yes | no) yes >
<!ELEMENT val - O (#PCDATA) >
<!ATTLIST val %a.global; >
<!-- Finally we define the elements specific to this DTD -->
<!-- ... declarations from section 27.1 -->
<!-- (The TagDoc element) -->
<!-- go here ... -->
<!-- ... declarations from section 27.1.1 -->
<!-- (Attribute documentation) -->
<!-- go here ... -->
<!-- ... declarations from section 27.2 -->
<!-- (Element classes) -->
<!-- go here ... -->
<!-- ... declarations from section 27.3 -->
<!-- (Entity Documentation) -->
<!-- go here ... -->
The <tagDoc> element is used to document an element type, together with its associated attributes. A completely specified <tagDoc> may comprise all of the following components in the order specified:
As the content model for <tagDoc> makes clear, only the <gi> , <desc> , <exemplum> , <dataDesc> , <parents> , <children> and <elemDecl> elements are mandatory components. For elements bearing attributes, the <attList> and <attlDecl> components are also required for TEI conformance. For compatibility with the TEI system, use of the <classes> and <files> elements is strongly recommended. The only components of the <tagDoc> element which can appear more than once are the <exemplum> , <ptr> and <equiv> elements. The order of components may not be changed.
The <tagDoc> and its constituents are defined as follows:
<!-- 27.1: The TagDoc element -->
<!ELEMENT tagDoc - - (gi, rs?, desc, attList?,
exemplum*, remarks?, part?,
classes?, files?, dataDesc?,
parents?, children?, elemDecl,
attlDecl?, ptr*, equiv*) >
<!ATTLIST tagDoc %a.global;
usage (req | mwa | rec | rwa | opt)
opt >
<!-- RS and PTR are defined in the core -->
<!-- GI is defined above -->
<!ELEMENT desc - O (%paraContent) >
<!ATTLIST desc %a.global; >
<!ELEMENT attList - O (attDef*) >
<!ATTLIST attList %a.global; >
<!ELEMENT exemplum - - (p*, eg, p*) >
<!ATTLIST exemplum %a.global; >
<!ELEMENT eg - - (#PCDATA) >
<!ATTLIST eg %a.global; >
<!ELEMENT remarks - O (%component.seq) >
<!ATTLIST remarks %a.global; >
<!ELEMENT part - O (#PCDATA) >
<!ATTLIST part %a.global;
name CDATA #IMPLIED
type CDATA #IMPLIED >
<!ELEMENT classes - O (#PCDATA) >
<!ATTLIST classes %a.global;
names CDATA #REQUIRED >
<!ELEMENT files - O EMPTY >
<!ATTLIST files %a.global;
names CDATA #IMPLIED >
<!ELEMENT dataDesc - O (%phrase.seq) >
<!ATTLIST dataDesc %a.global; >
<!ELEMENT parents - O (#PCDATA) >
<!ATTLIST parents %a.global; >
<!ELEMENT children - O (#PCDATA) >
<!ATTLIST children %a.global; >
<!ELEMENT elemDecl - O (#PCDATA) >
<!ATTLIST elemDecl %a.global; >
<!ELEMENT attlDecl - - (#PCDATA) >
<!ATTLIST attlDecl %a.global; >
<!ELEMENT equiv - O (%specialPara) >
<!ATTLIST equiv %a.global;
scheme CDATA #REQUIRED >
<!-- This fragment is used in sec. 27 -->
The <attList> element is used to document information about a collection of attributes, either within a <tagDoc> , or within a <classDoc> . It consists of a series of <attDef> elements, each documenting a single attribute and each using an appropriate selection from the following elements:
It will be noted that several of these elements are used identically to document both elements and attributes. Specific to attributes are <dataType> , <valList> , <valDesc> , <val> and <default> . For any attribute documented in this way, either a <valList> or a <valDesc> must be supplied to specify the range of permitted values for an attribute. A <valList> should be used if the intended set of values can be enumerated; a <valDesc> if it cannot. A legal <attDef> specification must contain an <attName> , a <desc> , a <datatype> , either a <valList> or a <valDesc> , and a default; the other elements listed above are all optional.
The <attList> within a <tagDoc> is used to specify only the attributes which are specific to that particular element. Attributes which are shared by other elements, or by all elements, should be documented by an <attList> contained within a <classDoc> element, as described in section 27.2 below.
The following <attList> demonstrates some of the possibilities; for more detailed examples, consult the tagged version of the reference material in these Guidelines.
<attDef usage=opt>
<attName>type
<desc>describes the form of the list.
<datatype>CDATA
<valList type=semi>
<val>ordered<desc>list items are numbered or lettered.
<val>bulleted<desc>list items are marked with a
<soCalled>bullet</soCalled> or other typographic device.
<val>simple<desc>list items are not numbered or bulleted.
<val>gloss<desc>each list item glosses some term or
concept, which is given by a <gi>label</gi> element preceding
the list item.
</valList>
<default>simple
<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.
</attDef>
Those elements from the above list which are unique to attributes are declared as follows:
<!-- 27.1.1: Attribute documentation -->
<!ELEMENT attDef - O (attName, rs?, desc, (dataType,
(valList | valDesc)?), default,
eg?, remarks?, equiv*) >
<!ATTLIST attDef %a.global;
usage (req | mwa | rec | rwa | opt)
opt >
<!ELEMENT attName - O (#PCDATA) >
<!ATTLIST attName %a.global; >
<!ELEMENT dataType - O (#PCDATA) >
<!ATTLIST dataType %a.global; >
<!ELEMENT valList - - ((val, desc)*) >
<!ATTLIST valList %a.global;
type (closed | semi | open)
open >
<!ELEMENT valDesc - O (%phrase.seq) >
<!ATTLIST valDesc %a.global; >
<!ELEMENT default - O (#PCDATA) >
<!ATTLIST default %a.global; >
<!-- This fragment is used in sec. 27 -->
The element <classDoc> is used to document an element class, as defined in section 3.7 . It has the following components:
The attribute type is used to distinguish between `model' and `attribute' classes; for the former, a <classDoc> simply exists so that members of the class it documents may point to it (by specifying the value of its id attribute among the values specified by the names attribute of their <classes> component); for the latter, the <classDoc> additionally contains an <attList> which specifies the attributes shared by the members of the class. A class may perform both functions, of course.
Where a class inherits properties or attributes from some other class, the <classes> element may be used to indicate this fact. Membership of an attribute class can be inherited by any class, but model-only classes may not include attribute-only classes amongst their members. For further discussion of the TEI class system, see section 3.7 .
The <classDoc> element and the elements unique to it are declared as follows:
<!-- 27.2: Element classes -->
<!ELEMENT classDoc - O (class, rs?, desc, attList?,
remarks?, part?, classes?, files?,
ptr*, equiv*) >
<!ATTLIST classDoc %a.global;
type (model | atts | both)
#IMPLIED >
<!ELEMENT class - O (#PCDATA) >
<!ATTLIST class %a.global; >
<!-- all other constituents are defined above -->
<!-- This fragment is used in sec. 27 -->
The <entDoc> element is used to document any other entity not otherwise documented by the elements described in this chapter. Its chief uses are to provide systematic documentation for parameter entities used within TEI DTD fragments (for example, those used to enable different components of the TEI DTD, or to describe common content models), but it may be used for any purpose. It has the following components:
The <entDoc> element and the elements unique to it are declared as follows:
<!-- 27.3: Entity Documentation -->
<!ELEMENT entDoc - - (entName, rs?, desc, remarks?,
string, ptr*, equiv*) >
<!ATTLIST entDoc %a.global;
type (pe | ge) #REQUIRED >
<!ELEMENT entName - O (#PCDATA) >
<!ATTLIST entName %a.global; >
<!ELEMENT string - - (#PCDATA) >
<!ATTLIST string %a.global; >
<!-- All other constituents are defined above -->
<!-- This fragment is used in sec. 27 -->
| Previous | Up | Next |