Previous | Up | Next

#### Part 5

### Auxiliary Document Types

# 27 Tag Set Documentation

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.

- `<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:
    - rwa recommended when applicable
    - rec recommended
    - mwa mandatory when applicable
    - req required
    - opt optional
- `<classDoc>` contains reference information for a TEI element class; that is a group of elements which appear together in SGML content models, or which share some common attribute, or both.
- `<entDoc>` formally documents a single SGML entity within an encoding scheme.

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.

- `<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 in 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, an appropriate parameter entity should be defined.

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

## 27.1 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:

- `<rs>` contains a general purpose name or referring string.
- `<gi>` contains the name (generic identifier) of an SGML element.
- `<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.

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

### 27.1.1 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:
    - rwa recommended when applicable
    - rec recommended
    - mwa mandatory when applicable
    - req required
    - opt optional
- `<attName>` contains the name of the attribute being defined by an `<attDef>` element.
- `<rs>` contains a general purpose name or referring 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:
    - 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.
    - closed only the values specified are permitted.
- `<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.

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

## 27.2 Element Classes

The element `<classDoc>` is used to document an element class, as defined in section 3.7 . It has the following components:

- `<classDoc>` contains reference information for a TEI element class; that is a group of elements which appear together in SGML content models, or which share some common attribute, or both. Attributes include:
  - `type` indicates whether this is a model class, an attribute class, or both. Sample values include:
    - atts members of this class share common attributes
    - both members of this class share attributes and also appear in the same SGML content models
    - model members of this class appear in the same SGML content models
- `<class>` specifies the name of an element class.
- `<rs>` contains a general purpose name or referring 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 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                         -->

## 27.3 Entity Documentation

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:

- `<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 referring 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.

Of these, only `<entName>` , `<desc>` and `<string>` are required components. If present, the other elements must be given in the order specified, and only `<ptr>` and `<equiv>` may be repeated.

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