This chapter defines an auxiliary tag set which may be used for the documentation of new SGML 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 and ; 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.Mutatis mutandis: at the time this chapter is released, the reference materials being published are still using an earlier version of this tag set; like the rest of the Guidelines, they will be modified to use this published tag set as soon as the Guidelines are completed. -Eds.

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. tsd contains a set of elements documenting an SGML tag set. tagDoc documents the structure, content, and purpose of a single SGML element type. Attributes include: usage specifies the optionality of an attribute or element. Legal values are: req required mwa mandatory when applicable rec recommended rwa recommended when applicable opt optional classDoc contains reference information for one element class; either elements which appear together in SGML content models, or elements which share some common attribute. entDoc formally documents a single SGML entity within an encoding scheme.

In addition, the following phrase-level elements may be found useful for marking up occurrences of element names, etc., within the body of running text. gi contains the name (generic identifier) of an SGML element. Attributes include: TEI indicates whether this element is part of the TEI encoding scheme (i.e., defined in a TEI DTD fragment) or not. Legal values are: yes this element is part of the TEI scheme. no this element is not part of the TEI scheme. att contains the name of an attribute appearing within running text. Attributes include: TEI indicates whether this attribute is part of the TEI scheme (i.e., defined in a TEI DTD fragment) or not. Legal values are: yes this attribute is part of the TEI scheme. no this attribute is not part of the TEI scheme. val contains a single attribute value. tag contains text of a complete SGML start- or end-tag, possibly including attribute specifications, but excluding the opening and closing markup delimiter characters. These four elements are included among the phrase-level elements available to any document using the auxiliary tag set defined in this chapter; to make them available to documents using other DTDs, they should be defined as extensions to the TEI tag sets, as described in chapter .

As an example of the recommended use of these elements, we quote from a TEI working paper: The gi element is used to tag element names when they appear in the text; the tag element however is used to show how a tag as such might appear. So one might talk of an occurrence of the blort element which had been tagged blort type='runcible' ... /blort. The type attribute may take any name token as value; the default value is spqr, in memory of its creator. ]]> Note that end-tags marked with the tag element must include a leading slash (/) in the element content, as shown.

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: %TEI.elementNames; %TEI.keywords.ent; %TEI.elementClasses; %TEI.core.dtd; ]]> The Tagdoc Documentation Element

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: gi contains the name (generic identifier) of an SGML element. rs contains a general purpose name or referencing string. desc contains a brief description of the purpose and application for an element, attribute, or attribute value. attList contains documentation for all the attributes associated with this element, as a series of attDef elements. exemplum contains a single example demonstrating the use of an element, together with optional paragraphs of commentary. eg contains a single example demonstrating the use of an element or attribute. If the example contains SGML markup, it must be enclosed within a marked CDATA section. remarks contains any commentary or discussion about the usage of an element, attribute, class, or entity not otherwise documented within the containing element. part specifies the module or part to which a particular element, element class, or entity belongs in a modular encoding scheme such as the TEI. classes specifies all the classes of which the documented element or class is a member or subclass. files specifies the name of the operating system file(s) within which this markup component is declared. dataDesc specifies the legal content of the element being documented, noting any semantic or application-dependent constraints, as well as constraints enforced by the SGML content model. parents lists elements which can directly contain this element. children lists the elements which this element may directly contain. elemDecl contains the full form of an SGML declaration for the element documented using the reference concrete syntax. attlDecl contains the SGML ATTLIST declaration associated with this element. ptr defines a pointer to another location in the current document in terms of one or more identifiable elements. equiv specifies an equivalent or comparable element in some other markup language.

If as is often the case the gi of an element is an abbreviation of a natural-language word or phrase, the rs element is used to provide the full form intended, which is important for mnemonic purposes. The ptr element is used to cross-refer to the relevant section(s) of any accompanying prose documentation.

As the content model for tagDoc makes clear, only the gi, desc, dataDesc, and elemDecl elements are mandatory components. For elements bearing attributes, the attList and attlDecl components are also required for TEI conformance. For consistency with the standard TEI reference materials, use of the classes, files, exemplum, parents, and children 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.

Several examples of complete tagDoc elements are provided in section .

The tagDoc element and its constituents are defined as follows: ]]> The AttList Documentation Element

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: attDef contains the definition of a single attribute. Attributes include: usage specifies the optionality of an attribute or element. Legal values are: req required mwa mandatory when applicable rec recommended rwa recommended when applicable opt optional attName contains the name of the attribute being defined by an attDef element. rs contains a general purpose name or referencing string. desc contains a brief description of the purpose and application for an element, attribute, or attribute value. dataType specifies an SGML declared value for an attribute. valList contains a list of value and description pairs for an attribute. Attributes include: type specifies the extensibility of the list of attribute values specified. Legal values are: closed only the values specified are permitted. semi all the values specified should be supported, but other values are legal and software should have appropriate fallback processing for them. open the values specified are sample values only. val contains a single attribute value. valDesc specifies any semantic or syntactic constraint on the value that an attribute may take, additional to the information carried by the dataType element. default specifies the default declared value for an attribute. eg contains a single example demonstrating the use of an element or attribute. If the example contains SGML markup, it must be enclosed within a marked CDATA section. remarks contains any commentary or discussion about the usage of an element, attribute, class, or entity not otherwise documented within the containing element. equiv specifies an equivalent or comparable element in some other markup language.

If as is often the case the name of an attribute is an abbreviation of a natural-language word or phrase, the rs element is used to provide the full form intended.

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

The following attList demonstrates some of the possibilities; for more detailed examples, refer to chapter . type describes the form of the list. CDATA ordered list items are numbered or lettered. bulleted list items are marked with a bullet or other typographic device. simple list items are not numbered or bulleted. gloss each list item glosses some term or concept, which is given by a label element preceding the list item. simple

The formal syntax of the element declarations allows label tags to be omitted from lists tagged list type=gloss; this is however a semantic error. ]]>

Those elements from the above list which are unique to attributes are declared as follows: ]]> Element Classes

The element classDoc is used to document an element class, as defined in section . It has the following components: classDoc contains reference information for one element class; either elements which appear together in SGML content models, or elements which share some common attribute. Attributes include: type indicates whether this is an model class, an attribute class, or both. Sample values include: model members of this class appear in the same SGML content models atts members of this class share common attributes both members of this class share attributes and appear in the same SGML content models class specifies the name of an element class. rs contains a general purpose name or referencing string. desc contains a brief description of the purpose and application for an element, attribute, or attribute value. attList contains documentation for all the attributes associated with this element, as a series of attDef elements. remarks contains any commentary or discussion about the usage of an element, attribute, class, or entity not otherwise documented within the containing element. part specifies the module or part to which a particular element, element class, or entity belongs in a modular encoding scheme such as the TEI. classes specifies all the classes of which the documented element or class is a member or subclass. ptr defines a pointer to another location in the current document in terms of one or more identifiable elements. equiv specifies an equivalent or comparable element in some other markup language. Of these elements, only the class and desc elements are required components. If present, the other elements must be given in the order specified, and only ptr and equiv may be repeated.

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 among their members. For further discussion of the TEI class system, see section .

For examples of attribute classes, please refer to chapter .

The classDoc element and the elements unique to it are declared as follows: ]]> Entity Documentation

The entDoc element is used to document any 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: entDoc formally documents a single SGML entity within an encoding scheme. Attributes include: type indicates whether this is a general or a parameter entity. Legal values are: pe parameter entity ge general entity entName contains the full name of an entity, excluding the percent sign in the case of a parameter entity. rs contains a general purpose name or referencing string. desc contains a brief description of the purpose and application for an element, attribute, or attribute value. remarks contains any commentary or discussion about the usage of an element, attribute, class, or entity not otherwise documented within the containing element. string contains the intended expansion for the entity documented by an entdoc element, enclosed by quotation marks. ptr defines a pointer to another location in the current document in terms of one or more identifiable elements. equiv specifies an equivalent or comparable element in some other markup language. As in the other documentation elements, rs is used in cases when the entity name itself is an abbreviation, to give the full natural-language word or phrase abbreviated, and ptr is used to give cross-references to any prose documentation. Of the elements named, only entName, desc and string are required components. If present, the other elements must be given in the order specified, and only xref and equiv may be repeated.

For examples, please refer to chapters and .

The entDoc element and the elements unique to it are declared as follows: ]]> Example

As described above, a tag set documentation file contains a series of tagDoc, classDoc, and entDoc elements, enclosed within a tsd element. The DTD for this auxiliary document type is contained in file teitsd2.dtd.

A complete tag set documentation file documenting the imaginary elements blort and granfalloon might thus have the following appearance: blort Contains a ... - O (%phrase.seq) granfalloon Contains an unsupported assertion or fantastic accusation. - - (%paraContent) ]]>