## Text Encoding Initiative

### The XML Version of the TEI Guidelines

# 38 Sample Tag Set Documentation

Up: Contents Previous: 37 Obtaining TEI WSDs Next: 39 Formal Grammar for the TEI-Interchange-Format Subset of SGML

This chapter gives some examples of the tagging actually used to document particular elements in the TEI scheme. The tagging here may be compared with the results for the corresponding element shown in the alphabetical reference section. Note however that the present version of the Guidelines uses an XML format which differs in a few respects from that documented in chapter 27 Tag Set Documentation.

#### 38.1 Tag Documentation for the TEI p Element

This example shows the documentation for the element `<p>`. Since this element has no attributes other than global attributes, its `<attList>` element is empty. For a formatted, printed version of this information, see the alphabetical reference section.

    <tagDoc id="P" usage="req">
      <gi>p</gi>
      <rs>paragraph</rs>
      <desc>marks paragraphs in prose.</desc>
      <attList/>
      <exemplum><eg><![CDATA[<p>Hallgerd was outside.
    	  <q>There is blood on your axe,</q> she said.
    	  <q>What have you done?</q>
    	</p>
    	<p><q>I have now arranged that you can be
    		married a second time,</q> replied Thjostolf.</p>
    	<p><q>Then you must mean that Thorvald is
    		dead,</q> she said.</p>
    	<p><q>Yes,</q> said Thjostolf.
    	  <q>And now you must think up some plan for me.</q>
    	</p>]&nil;]></eg></exemplum>
      <remarks>
    	<p>In some contexts, the paragraph may have a specialized
    	  meaning, e.g. in the tag set for dictionaries, <gi>p</gi> is used to
    	  enclose any running text, and thus does not imply text set off as is
    	  conventionally done in running prose.</p></remarks>
      <part type="top" name="core"/>
      <classes names="CHUNK"/>
      <dataDesc>May contain character data and phrase-level elements.</dataDesc>
      <elemDecl> %om.RO;  %paraContent;</elemDecl>
      <ptr target="COPA" type="div2"/>
      <ptr target="DRPAL" type="div2"/>
    </tagDoc>

#### 38.2 Tag Documentation for the TEI head Element

This example shows the documentation for the element `<head>`. In addition to the global attributes, this element defines an attribute of its own within an `<attList>` element. For a formatted, printed version of this information, see the alphabetical reference section.

    <tagDoc id="HEAD" usage="rwa">
      <gi>head</gi>
      <rs>heading</rs>
      <desc>contains any heading, for example, the title of a section,
    	or the heading of a list or glossary.</desc>
      <attList>
        <attDef usage="opt">
    	  <attName>type</attName>
    	  <desc>categorizes the heading in some way meaningful
    		to the encoder. </desc>
    	  <datatype>CDATA</datatype>
    	  <valDesc>A set of user-defined keywords may be employed. Their
    		significance should be documented in the header.
    	  </valDesc>
    	  <default>#IMPLIED</default>
    	</attDef>
      </attList>
      <exemplum>
    	<p>The most common use for the <gi>head</gi> element is to mark the headings
    	  of sections.  In older writings, the headings or <term>incipits</term> may
    	  be rather longer than usual in modern works. If a section has an explicit
    	  ending as well as a heading, it should be marked as a <gi>trailer</gi>, as
    	  in this example:</p>
    	<eg><![CDATA[<div1 n="I" type="book">
      <head>In the name of Christ here begins the first book of the ecclesiastical
    	 history of Georgius Florentinus, known as Gregory, Bishop of Tours.</head>
      <list type="simple">
        <head>Chapter-Headings</head>
        <!-- list of chapter heads omitted ...  -->
      </list>
      <div2 type="section">
      <head>In the name of Christ here begins Book I of the history.</head>
      <p>Proposing as I do ...</p>
      <!-- ... -->
      <p>From the Passion of our Lord until the death of Saint Martin four
    	 hundred and twelve years passed.</p>
      <trailer>Here ends the first Book, which covers five thousand, five
    	 hundred and ninety-six years from the beginning of the world
    	 down to the death of Saint Martin.</trailer>
      </div2>
    </div1>]&nil;]></eg></exemplum>
      <exemplum>
    	<p>The <gi>head</gi> tag is also used to mark headings
    	  of other units, such as lists:</p>
    	<eg><![CDATA[With a few exceptions, connectives are equally useful in
    all kinds of discourse: description, narration, exposition,
    argument.
    <list type="simple">
     <head>Connectives</head>
     <item>above</item>
     <item>accordingly</item>
     <item>across from</item>
     <item>adjacent to</item>
     <item>again</item>
     <!-- ... -->
    </list>]&nil;]></eg></exemplum>
      <remarks>
    	<p>The <gi>head</gi> tag is used for headings at all levels; processing
    	  programs which treat (e.g.) chapter headings, section headings, and list
    	  titles differently must determine the proper processing of a <gi>head</gi>
    	  element based on its structural position.  A <gi>head</gi> occurring as
    	  the first element of a list is the title of that list; one occurring as
    	  the first element of a <gi>div1</gi> is the title of that chapter or
    	  section.</p></remarks>
      <part type="top" name="core"/>
      <classes names="DIVTOP FMCHUNK"/>
      <dataDesc>May contain character data and phrase-level elements.</dataDesc>
      <elemDecl> %om.RO; %paraContent;</elemDecl>
      <ptr target="COLI" type="div2"/>
      <ptr target="DSDTB" type="div2"/>
    </tagDoc>

#### 38.3 Tag Documentation for the TEI div Element

The example below shows the documentation for the `<div>` element; this element is a member of the class divn, the documentation for which is shown further below.

    <tagDoc id="DIV" usage="rwa">
      <gi>div</gi>
      <rs>text division</rs>
      <desc>contains a subdivision of the front, body, or back of a text.</desc>
      <attList/>
      <exemplum> <eg><![CDATA[<body>
      <div type="part"><head>Fallacies of Authority</head>
        <p>The subject of which is Authority in various shapes, and the
          object, to repress all exercise of the reasoning faculty.</p>
        <div n="1" type="chapter"><head>The Nature of Authority</head>
          <p>With reference to any proposed measures having for their
            object the greatest happiness of the greatest number ...</p>
          <div n="1.1" type="section"><head>Analysis of Authority</head>
            <p>What on any given occasion is the legitimate weight or
              influence to be attached to authority ...</p>
          </div><!-- end of section 1.1 -->
          <div n="1.2" type="section">
            <head>Appeal to Authority, in What Cases Fallacious.</head>
            <p>Reference to authority is open to the charge of fallacy when ...</p>
          </div><!-- end of section 1.2 -->
          <!-- other sections here -->
        </div><!-- end of chapter 1 -->
        <!-- other chapters here -->
      </div><!-- end of part A -->
      <!-- other parts here -->
    </body>]&nil;]></eg> </exemplum>
      <remarks/>
      <!-- J Bentham: Handbook of Political Fallacies (1824), ed -->
      <!-- Larrabee, Johns Hopkins Pr, 1952 -->
      <part type="base" name="core"/>
      <classes names="DIVN DECLING"/>
      <dataDesc>any sequence of low-level structural elements, possibly
    	grouped into lower subdivisions.</dataDesc>
      <elemDecl>%om.RO; ( (%m.divtop; | %m.Incl; )*, (((div|divGen),
    	(%m.Incl;)*)+ | ((%component;, (%m.Incl;)*)+,
    	((div|divGen), (%m.Incl;)*)*)),
    	((%m.divbot;),(%m.Incl;)*)*)
      </elemDecl>
      <ptr target="DSDIV"/> <ptr target="TEDT"/> <ptr target="DSDIV1"/>
    </tagDoc>

#### 38.4 Class Documentation for the TEI Divn Class

The example below shows the documentation for the class divn, which is referred to by the documentation for `<div>` shown above.

    <classDoc id="DIVN" type="atts">
      <class>divn</class>
      <desc>structural elements which behave in the same way as divisions.</desc>
      <attList>
        <attDef usage="rec">
          <attName>type</attName>
          <desc>specifies a name conventionally used for this level of
            subdivision, e.g. <q>act</q>, <q>volume</q>, <q>book</q>,
            <q>section</q>, <q>canto</q>, etc.</desc>
          <datatype>CDATA</datatype>
          <valDesc>any string of characters</valDesc>
          <default>CDATA</default>
        </attDef>
        <attDef usage="opt">
          <attName>org</attName>
          <desc>specifies how the content of the division is organized.</desc>
          <datatype>(composite | uniform)</datatype>
          <valList type="closed">
            <val>composite</val>
            <desc>composite content: i.e. no claim is made about the
              sequence in which the immediate contents of this division
              are to be processed, or their inter-relationships.</desc>
            <val>uniform</val>
            <desc>uniform content: i.e. the immediate contents of this
              element are regarded as forming a logical unit, to be
              processed in sequence.</desc>
          </valList>
          <default>uniform</default>
        </attDef>
        <attDef usage="opt">
          <attName>sample</attName>
          <desc>indicates whether this division is a sample of the
            original source and if so, from which part.</desc>
          <datatype>(initial | medial | final | unknown | complete)</datatype>
          <valList type="closed">
            <val>initial</val><desc>division lacks material present at end in source.</desc>
            <val>medial</val><desc>division lacks material at
              start and end.</desc>
            <val>unknown</val>
            <desc>position of sampled material within original
              unknown.</desc>
            <val>complete</val><desc>division is not a sample.</desc>
          </valList>
          <default>complete</default>
          <remarks/>
        </attDef>
        <attDef usage="mwa"><attName>part</attName>
          <desc>specifies whether or not the division is fragmented by some other
            structural element, for example a speech which is divided between two
            or more verse stanzas.
          </desc>
          <datatype>(Y | N | I | M | F)</datatype>
          <valList type="closed">
            <val>Y</val><desc>the division is incomplete in some respect</desc>
            <val>N</val><desc>either the division is complete, or no claim is made as to
              its completeness.</desc>
            <val>I</val><desc>the initial part of an incomplete division</desc>
            <val>M</val><desc>a medial part of an incomplete division</desc>
            <val>F</val><desc>the final part of an incomplete division</desc>
          </valList>
          <default>N</default>
          <remarks><p>The values I, M, or F should be used only where it is
              clear how the division is to be reconstituted.</p>
          </remarks>
        </attDef>
      </attList>
      <part type='base' name='core'>base tag set for common core
        features</part>
      <classes names=''/>
      <files names='teiclas2.ent'/>
      <ptr target="DS"/>
    </classDoc>

Up: Contents Previous: 37 Obtaining TEI WSDs Next: 39 Formal Grammar for the TEI-Interchange-Format Subset of SGML