<?tei:SOF p2hd5.odd ?>
<!-- $Id: p2hd5.odd,v 1.10 1998/01/31 19:50:52 tei Exp $ -->
<!--*
    * $Log: p2hd5.odd,v $
    * Revision 1.10  1998/01/31 19:50:52  tei
    * Change system 'tei2.dtd' to public identifier
    * fix log keyword (if not already fixed)
    * normalize the sgml
    *
    * Revision 1.9  98/01/28  11:09:58  cmsmcq
    * LB changes of January 1998
    * 
    * Revision 1.8  1994/04/01  16:23:58  msmcq
    * Misc. changes/fixes while validating DTDs
    * 
    * Revision 1.7  1994/03/24  22:14:56  msmcq
    * typo corrections from David Barnard, Peter Robinson, and others
    * 
    * Revision 1.6  1994/01/28  18:04:57  lou
    * add fsdDecl and metDecl
    * 
    * Revision 1.2  1993/06/22  14:29:49  msmcq
    * Changes post Eynsham and for DTD generation
    * -->
<!-- Revisions:                                               -->
<!-- 10 jan 98 : LB : fixing egs -->
<!-- 4 Jan 98 : LB : changed wsd to fsd in eg -->
<!-- 94-03-29 : MSM : suppress supererogatory file att on dtdfrags -->
<!-- 94-03-29 : MSM : add varencod                            -->
<!-- 94-03-24 : CMSMcQ : more typos, from Peter R             -->
<!-- 94-03-22 : CMSMcQ : typos, TEI - &tei, code, ident tags  -->
<!-- 22 jan 94 : LB : add metdecl and fsdDecl -->
<!-- 9 jan : LB: samplingDecl, not Desc -->
<!-- 28 dec 93: LB: INTERP changed to INTERPTN  -->
<!-- 93-06-21 : MSM : change file id on dtdfrags              -->
<!-- 93-06-01 : MSM : add dtdfrag for tagsdecl                -->
<!-- 93-06-01 : MSM : add tagsDecl section (from LB)          -->
<!--                  add example of samplingDecl to show     -->
<!--                  documentation of systematic omissions   -->
<!-- 93-06-01 : MSM : misc normalizations                     -->
<!-- 93-02-10 : MSM : update xref targets                     -->
<!-- 92-08-19 : MSM : Change straggling refs to ANALYSIS      -->
<!-- 92-08-18 : MSM : revisions as per LB talk                -->
<!-- 92-08-18 : MSM : change -isa- -ise- to -iza- -ize-       -->
<!-- 92-08-17 : MSM : Change ANALYSIS to INTERP               -->
<!-- 92-08-14 : MSM : revisions, clarifications               -->
<!-- 2 Aug 92: further revisions for consistency (LB) -->
<!-- 25 Jul 92 : MSM : names updated, ids updated             -->

<div2 id="HD5"><head>The Encoding Description</head>
 
<p>The <gi>encodingDesc</gi> element is the second major subdivision of
the &tei; header.  It specifies the methods and editorial principles which
governed the transcription or encoding of the text in hand and may also
include sets of coded definitions used by other components of the
header.  Though not formally required, its use is highly recommended.
<tagList>
<tagDesc tagDoc="ENCDESC">
</tagList>
The content of the encoding description may be a prose description, or
it may contain elements from the following list, in the order given:
<tagList>
<tagDesc tagDoc="PROJDESC">
<tagDesc tagDoc="SAMPDECL">
<tagDesc tagDoc="EDDECL">
<tagDesc tagDoc="TAGSDECL">
<tagDesc tagDoc="REFSDECL">
<tagDesc tagDoc="CLASDECL">
<tagDesc tagDoc="FSDDECL">
<tagDesc tagDoc="METDECL">
<tagDesc tagDoc="VARENCOD">
</tagList>
 
Each of these elements is further described and formally defined
in the appropriate section below. The encoding description itself
is defined as follows:
 
<dtdFrag id="D225" n="The encoding description">
<tagDecl tagDoc="ENCDESC">
<dtdRef dtdFrag="D2251">
<dtdRef dtdFrag="D2252">
<dtdRef dtdFrag="D2253">
<dtdRef dtdFrag="DHD57">
<dtdRef dtdFrag="D2254">
<dtdRef dtdFrag="D2255">
<dtdRef dtdFrag="D2256">
<dtdRef dtdFrag="D2258">
<dtdRef dtdFrag="DHDVAR">
</dtdFrag></p>
 
<div3 id="HD51"><head>The Project Description</head>
 
<p>The <gi>projectDesc</gi> element is the first of the nine optional
subdivisions of the <gi>encodingDesc</gi> element.  It may be used to
describe, in prose, the purpose for which the electronic file was
encoded, together with any other relevant information concerning the
process by which it was assembled or collected.  This is of particular
importance for corpora or miscellaneous collections, but may be of use
for any text, for example to explain why one kind of encoding practice
has been followed rather than another.
<tagList>
<tagDesc tagDoc="PROJDESC">
</tagList></p>
<p>For example:
<eg>
<![ CDATA[
 <encodingDesc>
 <projectDesc><p>Texts collected for use in the
    Claremont Shakespeare Clinic, June 1990.
 </encodingDesc>
]]>
</eg></p>
 
<p>This element has the following formal declaration:
<dtdFrag id="D2251" n="The project description">
<tagDecl tagDoc="PROJDESC">
</dtdFrag></p></div3>
 
<div3 id="HD52"><head>The Sampling Declaration</head>
 
<p>The <gi>samplingDecl</gi> element is the second of the nine optional
subdivisions of the <gi>encodingDesc</gi> element.  It contains a prose
description of the rationale and methods used in sampling texts, for
example to create a representative corpus.
<tagList>
<tagDesc tagDoc="SAMPDECL">
</tagList>
It should include information about such matters as
 
<list type="bullets">
<item>the size of individual samples</item>
<item>the method or methods by which they were selected</item>
<item>the underlying population being sampled</item>
<item>the object of the sampling procedure used</item>
</list>
 
but is not restricted to these.
<!-- should attributes be used for sample size, etc? -LB -->
<!-- if it would help automatic processing yes.  but i   -->
<!-- doubt it.  so no.  -msm                             -->
 
<eg>
<![ CDATA [
<samplingDecl>
  <p>Samples of 2000 words taken from the beginning of the text.
</samplingDecl>
]]>
</eg></p>
 
<p>It may also include a simple
description of any parts of the source text included or excluded.
 
<eg>
<![ CDATA [
<samplingDecl>
  <p>Text of stories only has been transcribed.
     Pull quotes, captions, and advertisements have been
     silently omitted.  Any mathematical expressions
     requiring symbols not present in the ISOnum or
     ISOpub entity sets have been omitted, and their
     place marked with a GAP element.
</samplingDecl>
]]>
</eg></p>
 
<p>A sampling declaration which applies to more than one text or
division of a text need not be repeated in the header of each such text.
Instead, the <att>decls</att> attribute of each text (or subdivision of
the text) to which the sampling declaration applies may be used to
supply a cross reference to it, as further described in section <xref
target="CCAS">.
<!-- was:  target=P2.3431>. -->
<!-- was:  target=SP31>. -->
This element has the following formal declaration:
 
<dtdFrag id="D2252" n="The sampling declaration">
<tagDecl tagDoc="SAMPDECL">
</dtdFrag></p></div3>
 
<div3 id="HD53"><head>The Editorial Practices Declaration</head>
 
<p>The <gi>editorialDecl</gi> element is the third of the nine optional
subdivisions of the <gi>encodingDesc</gi> element.  It is used to
provide details of the editorial practices applied during the encoding
of a text.
<tagList>
<tagDesc tagDoc="EDDECL">
</tagList>
It may contain a prose description only, or one or more of the following
specialized elements:
 
<tagList>
<tagDesc tagDoc="CORRECTN" atts="status method">
<tagDesc tagDoc="NORMALZN" atts="source method">
<tagDesc tagDoc="QUOTN" atts="marks form">
<tagDesc tagDoc="HYPHEN" atts="eol">
<tagDesc tagDoc="SEGMENTN">
<tagDesc tagDoc="STDVALS">
<tagDesc tagDoc="INTERPTN">
</tagList>
 
<!-- PR urges for P4 a clearer distinction between            -->
<!-- proofreading and editorial correction.                   -->
 
Some of these elements carry attributes to support automated processing
of certain well-defined editorial decisions; all of them contain a prose
description of the editorial principles adopted with respect to the
particular feature concerned.  Examples of the kinds of questions which
these descriptions are intended to answer are listed below, in the same
order as the list above.
 
<list type="gloss">
 
<label><gi>correction</gi></label>
<item>Was the text corrected during or after data capture?  If
so, were corrections made silently or are they marked using the
tags described in section <xref target="COED">?  What principles
<!-- was:  target='P2.47' -->
<!-- was:  target='COEDIT'-->
have been adopted with respect to omissions, truncations, dubious
corrections, alternate readings, false starts, repetitions, etc.?</item>
 
<label><gi>normalization</gi></label>
<item>Was the text normalized, for example by regularizing any
non-standard spellings, dialect forms, etc.?  If so, were normalizations
performed silently or are they marked using the tags described in
section <xref target="COED">?
<!-- was:  target='P2.47' -->
<!-- was:  target='COEDIT' -->
What authority was used for the regularization?  Also, what principles
were used when normalizing dates or numbers to provide the standard
values for the <att>value</att> attribute described in sections <xref
target="CONANU"> and <xref target="CONADA">
<!-- was:  target='P2.23a'  and target='P2.23b'  -->
<!-- was:  target='CONUMS'  and target='CODATE'  -->
and what format used for them?</item>
 
<label><gi>quotation</gi></label>
<item>How were quotation marks processed?  Are apostrophes and quotation
marks distinguished?  How?  Are quotation marks retained as content in
the text or replaced by markup?  Was the <att>rendition</att> attribute
used to record the specific appearance of any quotation marks removed
from the text?  Are there any special conventions regarding for example
the use of single or double quotation marks when nested?  Is the file
consistent in its practice or has this not been checked?</item>
 
<label><gi>hyphenation</gi></label>
<item>Does the encoding distinguish <soCalled>soft</soCalled> and
<soCalled>hard</soCalled> hyphens?
What principle has been adopted with respect to end-of-line hyphenation
where source lineation has not been retained?  Have soft hyphens been
silently removed, and if so what is the effect on lineation and
pagination?</item>
 
<label><gi>segmentation</gi></label> <item>How is the text segmented?  If
<gi>s</gi> or <gi>seg</gi> segmentation units have been used to divide
up the text for analysis, how are they marked and how was the
segmentation arrived at?</item>
 
<label><gi>stdVals</gi></label>
 
<item>What standardization methods underly any standardized values
supplied for numeric values or dates?  If the <att>value</att> attribute
described in section <xref target="CONADA"> has been used,
<!-- was:  target='P2.23b' -->
<!-- was:  target='CODATE' -->
in what format are its values presented?</item>
 
<label><gi>interpretation</gi></label>
<item>Has any analytic or <soCalled>interpretive</soCalled> information
been provided --- that is, information which is felt to be non-obvious,
contentious, or subject to disagreement? If so, how was it generated?
How was it encoded? If feature-structure analysis has been used, are
<gi>fsdDecl</gi> elements (section <xref target="HDFSD">) present?</item>
</list></p>
 
<p>Any information about the editorial principles applied not falling
under one of the above headings should be recorded in a distinct list
of items.  Experience shows that a full record should be kept of
decisions relating to editorial principles and encoding practice,
both for future users of the text and for the project which produced
the text in the first instance.
 
<!-- Need at least one example!  But I don't have time to     -->
<!-- to add one.   in haste, -msm                             -->
A simple example follows:
<eg>
<![ CDATA [
<editorialDecl id=E2>
<interpretation>
  <p>The part of speech analysis applied throughout section 4 was
  added by hand and has not been checked.
<correction><p>Errors in transcription controlled by using the
    WordPerfect spelling checker.
<normalization source=W9>
  <p>All words converted to Modern American spelling using
    Websters 9th Collegiate dictionary.
<quotation marks=all form=std>
  <p>All opening quotation marks converted to &odq; all closing
    quotation marks converted to &cdq;.
</editorialDecl>
]]>
</eg>
<!-- an unresolved problem: where do I store the full citation -->
<!-- to which 'W9' is meant to be pointing at? -->
<!-- DB objects to '&amp;odq;' as "indecipherable" (msm)      --></p>
 
<p>These elements are formally defined as follows:
<dtdFrag id="D2253" n="The editorial practices declaration">
<tagDecl tagDoc="EDDECL">
<tagDecl tagDoc="CORRECTN">
<tagDecl tagDoc="NORMALZN">
<tagDecl tagDoc="QUOTN">
<tagDecl tagDoc="HYPHEN">
<tagDecl tagDoc="SEGMENTN">
<tagDecl tagDoc="STDVALS">
<tagDecl tagDoc="INTERPTN">
</dtdFrag>
 
An editorial practices declaration which applies to more than one text
or division of a text need not be repeated in the header of each such
text.  Instead, the <att>decls</att> attribute of each text (or
subdivision of the text) to which it applies may
be used to supply a cross reference to it, as further described in
section <xref target="CCAS">.
<!-- was:  target=P2.3431>. -->
<!-- was:  target=SP31>. --></p></div3>
 
<div3 id="HD57"><head>The Tagging Declaration</head>
 
<p>The <gi>tagsDecl</gi> element is the fourth of the nine optional
subdivisions of the <gi>encodingDesc</gi> element.  It is used to record
the following information about the tagging used within a particular
text:
<list>
<item>how often particular SGML elements appear within the text, so that
a recipient can validate the integrity of a text during interchange.</item>
<item>any comment relating to the usage of particular elements not
specified elsewhere in the header.</item>
<item>a definition for the default rendition applying to all instances
of an element, unless otherwise stated by the global <att>rend</att>
attribute.</item>
</list></p>
 
<p>This information is conveyed by the following elements:
<tagList>
<tagDesc tagDoc="RENDITN">
<tagDesc tagDoc="TAGUSAGE" atts="occurs ident render">
</tagList></p>
 
<p>The <gi>tagsDecl</gi> element consists of an optional sequence of
<gi>rendition</gi> elements, each of which must bear a unique
identifier, followed by a sequence of <gi>tagUsage</gi> elements, one
for each distinct element occurring within the outermost
<gi>text</gi> element of a &tei; document.</p>
 
<p>The <gi>rendition</gi> element defined in this version of the &tei;
Guidelines is a preliminary proposal only, intended to provide a hook
for more detailed specifications of default rendition in later versions.
 
<!-- Or think of it as the VAL attribute on MSM's -->
<!-- proposed SETREND element... --></p>
 
<p>The present proposal allows the encoder to enter an informal
description of a rendition, or style, as running prose only. This
rendition will be assumed to apply, by default, to all occurrences of
an element which names its identifier as the value of the
<att>render</att> attribute of the appropriate <gi>tagUsage</gi>
element. For element occurrences to which this default rendition does
not apply, the encoder should specify an explicit description using the
global <att>rend</att> attribute on the elements concerned.</p>
 
<p>For example, the following schematic shows how an encoder might
specify that <gi>p</gi> elements are by default to be rendered using one
set of specifications identified as <code type="value">style1</code>,
while <gi>hi</gi>
elements are to use a different set, identified as <code type="value">style2</code>:
 
<eg>
<![ CDATA [
<tagsDecl>
 <rendition id=STYLE1>
   <!-- description of one default rendition here -->
 <rendition id=STYLE2>
   <!-- description of another default rendition here -->
 <tagUsage gi=p render=style1>
 <tagUsage gi=hi render=style2>
</tagsDecl>
]]>
</eg></p>
 
 
<p>No detailed proposals for the content of the <gi>rendition</gi>
element have as yet been formulated.  It is probable that subsequent
work will incorporate specifications derived from, or compatible with,
the properties currently being standardized as part of the draft
Document Style and Semantics Specification Language (ISO DIS 10179).</p>
 
<p>A <gi>tagsDecl</gi> need not specify any <gi>rendition</gi> element.
If present, it must however contain exactly one occurrence of a
<gi>tagUsage</gi> element for each distinct element marked within the
outermost <gi>text</gi> element associated with the <gi>teiHeader</gi>
in which it appears.<note>This implies that the <gi>tagsDecl</gi> will
normally only appear in the header of individual texts in a
<gi>teiCorpus</gi>.</note> The <gi>tagUsage</gi> element is used to
supply a count of the number of occurrences of this element within the
text, which is given as the value of its <att>occurs</att> attribute.
It may also be used to hold any additional usage information, which is
supplied as running prose within the element itself.</p>
 
<p>For example:
 
<eg>
<![ CDATA [
  <tagUsage gi=hi occurs=28>
      Used only to mark English words italicised in the copy text.
  </tagUsage>
]]>
</eg>
 
This indicates that the <gi>hi</gi> element appears a total of 28 times
in the <gi>text</gi> element in question, and that the encoder has used
it to mark italicised English phrases only.</p>
 
<p>The <att>ident</att> attribute may optionally be used to specify how
many of the occurrences of the element in question bear a value for the
global <att>id</att> attribute, as in the following example:
 
 
<eg>
<![ CDATA [
  <tagUsage gi=pb occurs=321 ident=321>
      Marks page breaks in the York (1734) edition only
  </tagUsage>
]]>
</eg>
 
This indicates that the <gi>pb</gi> element occurs 321 times, on each
of which an identifier is provided.</p>
 
<p>The content of the <gi>tagUsage</gi> element is not susceptible of
automatic processing.  It should not therefore be used to hold
information for which provision is already made by other components of
the encoding description.  A &tei; conformant document is not required
to contain a <gi>tagsDecl</gi> element, but if one is present, it must
contain <gi>tagUsage</gi> elements for each distinct element marked in
the associated text, and the counts specified by their <att>usage</att>
elements must correspond with the number of such elements present in the
document, as identified by some conforming SGML processor.
 
<!-- the document's Element Structure Information Set, that   -->
<!-- is, as identified by any conforming SGML processor.      -->
 
<!-- OK? YHBW! -->
<!-- I don't think we should refer to ESIS without defining it. -->
<!-- I don't think we should get into defining ESIS here.     -->
<!-- Therefore I don't think we should refer to it here.      -->
<!-- But how else do we say it?  -msm                         -->
<!-- without mentioning ESIS. -msm                            -->
 
<dtdFrag id="DHD57" n="Tag usage and rendition declarations">
<tagDecl tagDoc="TAGSDECL">
<tagDecl tagDoc="TAGUSAGE">
<tagDecl tagDoc="RENDITN">
</dtdFrag></p></div3>
 
<div3 id="HD54"><head>The Reference System Declaration</head>
 
<p>The <gi>refsDecl</gi> element is the fifth of the nine optional
subdivisions of the <gi>encodingDesc</gi> element. It is used to
document the way in which any standard referencing scheme built into
the encoding works, either as a series of prose paragraphs or by
using the following specialized elements:
 
<tagList>
<tagDesc tagDoc="REFSDECL" atts="doctype">
<tagDesc tagDoc="STEP">
<tagDesc tagDoc="STATE">
</tagList>
 
Note that not all possible referencing schemes are equally easily
supported by current software systems.  A choice must be made between
the convenience of the encoder and the likely efficiency of the
particular software applications envisaged, in this context as in many
others.  For a more detailed discussion of referencing
systems supported by these Guidelines, see section <xref target="CORS"> below.
<!-- was:  target=CORSYS> -->
<!-- was:  target=P2.232> --></p>
 
<p>A referencing scheme may be described in one of three ways using this
element:
 
<list type="bullets">
<item>as a prose description</item>
<item>as a series of <term>steps</term> expressed in the TEI
extended pointer notation (documented in section <xref target="SAXR">)</item>
<item>as a concatenation of sequentially organized
<term>milestones</term></item>
</list>
 
Each method is described in more detail below.  Only one method can be
used within a single <gi>refsDecl</gi> element.</p>
 
<p>More than one <gi>refsDecl</gi> element can be included in the header
if more than one canonical reference scheme is to be used in the same
document, but the current proposals do not check for mutual
inconsistency.  A reference declaration can only describe the
referencing system applicable to a single document type; if therefore
concurrent document types are in use (as discussed in section <xref
target="CORS">), a <gi>refsDecl</gi> element must be supplied for each;
the <att>doctype</att> attribute should be used to specify the document
type to which the declaration relates.</p>
 
<div4 id="HD54P"><head>Prose Method</head>
 
<p>The referencing scheme may be specified within the <gi>refsDecl</gi>
by a simple prose description.  Such a description should indicate which
elements carry identifying information, and whether this information is
represented as attribute values or as content.  Any special rules about
how the information is to be interpreted when reading or generating a
reference string should also be specified here.  Such a prose
description cannot be processed automatically, and this method of
specifying the structure of a canonical reference system is therefore
not recommended for automatic processing.</p>
 
<p>For example:
 
<eg><![ CDATA[
 <refsDecl>
 <p>The N attribute of each text in this corpus carries
 a unique identifying code for the whole text. The title
 of the text is held as the content of the first HEAD
 element within each text. The N attribute on each DIV1
 and DIV2 contains the canonical reference for
 each such division, in the form 'XX.yyy', where XX
 is the book number in Roman numerals, and yyy the section
 number in arabic. Line breaks are marked by empty LINEBREAK
 tags, each of which includes the through line number
 in Casaubon's edition as the value of its N attribute.
 <p>The through line number and the text identifier
 uniquely identify any line. A canonical reference
 may be made up by concatenating the the N values from the
 text, div1 or div2 and calculating the line number within
 each part.
 </refsDecl>
]]>
</eg></p></div4>
 
<div4 id="HD54S"><head>Stepwise Method</head>
 
<p>This method defines each reference as a series of <term>steps</term>,
each of which corresponds to a single pair of expressions in the TEI
extended pointer notation (for which see section <xref target="SAXR">).
Often, but not always, each step will also correspond to one portion of
the canonical reference itself; in many common forms of canonical
reference, each step will narrow the scope within which the next step
can be taken.  The <gi>refsDecl</gi> element must specify the steps,
delimiters and lengths to be used by an application program, both when
constructing references for a given location and when interpreting
canonical references within a given document hierarchy.  It does so by
supplying one or more <gi>step</gi> elements, each of which identifies
the type of <soCalled>reference unit</soCalled> handled by the step and
uses a pair of extended-pointer expressions to indicate the starting and
ending pointers of the portion of the document which corresponds to a
given portion of the reference string.  The element may also give either
a delimiter or a length for use in breaking the corresponding reference
string up into units.
 
<tagList>
<tagDesc tagDoc="STEP" atts="refunit from to delim length">
</tagList></p>
 
<p>For example, the reference <q>Matthew 5:29</q> might be constructed
by stepping down the tree to find an element labelled as the
<q>Matthew</q> node, then within that to the <q>5</q> node, and finally,
within that, to the <q>29</q> node.  The following declarations would be
required; the special values <code type="value">%1</code>, <code
type="value">%2</code>, and <code type="value">%3</code> refer here to the
strings <cited>Matthew</cited>, <cited>5</cited>, and <cited>29</cited>,
respectively.
 
<eg>
<![ CDATA [
<refsDecl>
    <step refunit='book' delim=' '
          from='DESCENDANT (1 DIV1 N %1)'>
    <step refunit='chapter' delim=':'
          from='DESCENDANT (1 DIV2 N %2)'>
    <step refunit='verse'
          from='DESCENDANT (1 DIV3 N %3)'>
</refsDecl>
]]>
</eg>
 
As this example also shows, the steps of such a reference are typically
separated by fixed character sequences, called <term>delimiters</term>.
In this example, the delimiters are a space (following <q>Matthew</q>)
and a colon (following the chapter number).  A processor for canonical
references would use the delimiters specified by the <att>delim</att>
attributes to break the reference string up into pieces; the pieces
would then be used to interpret the <code type="value">%1</code>, etc., in
the extended pointer expressions of the <att>from</att> and
<att>to</att> attributes.</p>
 
<p>An alternative to the use of delimiters is to specify a fixed length
for each step of the reference:  for example, the same reference might
be given as <q>MAT05029</q>, assuming a fixed length of 3 for the first
step, 2 for the second and 3 for the third.
 
<eg>
<![ CDATA [
<refsDecl>
    <step length=3
          from='DESCENDANT (1 DIV1 N %1)'>
    <step length=2
          from='DESCENDANT (1 DIV2 N %2)'>
    <step length=3
          from='DESCENDANT (1 DIV3 N %3)'>
</refsDecl>
]]>
</eg>
 
The order in which the <gi>step</gi> elements are supplied corresponds
here with the order of elements within the reference, with the largest
(that is, the one nearest the top of the document hierarchy) item first
and the smallest last.</p>
 
<p>For a description of the processing required when a canonical
reference defined by <gi>step</gi> elements is to be recognized,
and examples of its use, see chapter <xref target="CR">.
 
<!-- following material deleted (regretfully) as too detailed: should -->
<!-- all go to section CREF --></p></div4>
 
<div4 id="HD54M"><head>Milestone Method</head>
 
<p>This method is appropriate when only <soCalled>milestone</soCalled>
tags (see section <xref target="CORS5">) are available to provide the
required referencing information.  It does not provide any abilities
which cannot be mimicked by the stepwise referencing method discussed in
the previous section, but in the cases where it applies, it provides a
somewhat simpler notation.</p>
 
<p>A reference based on milestone tags concatenates the values specified
by one or more such tags.  Since each tag marks the point at which a
value changes, it may be regarded as specifying the <term>state</term>
of a variable.  A reference declaration using this method therefore
specifies the individual components of the canonical reference as a
sequence of <gi>state</gi> elements:
 
<tagList>
<tagDesc tagDoc="STATE" atts="ed unit delim length">
</tagList></p>
 
<p>For example, the reference <q>Matthew 12:34</q> might be thought of
as representing the state of three variables:  the <q>book</q> variable
is in state <q>Matthew</q>; the <ident type="var">chapter</ident> variable
is in state <q>12</q>, and the <ident type="var">verse</ident> variable is
in state <q>34</q>.  If milestone tagging has been used, there should be
a tag marking the point in the text at which each of the above
<soCalled>variables</soCalled> changes its state.<note place="foot">On the
milestone tag itself, what are here referred to as
<soCalled>variables</soCalled> are identified by the combination of the
<att>ed</att> and <att>unit</att> attributes.</note>
To find <q>Matthew 12:34</q> therefore an application must scan left to
right through the text, monitoring changes in the state of each of these
three variables as it does so.  When all three are simultaneously in the
required state, the desired point will have been reached.  There may of
course be several such points.</p>
 
<p>The <att>delim</att> and <att>length</att> attributes are used to
specify components of a canonical reference using this method in exactly
the same way as for the stepwise method described in the preceding
section.  The other attributes are used to determine which instances of
<gi>mileStone</gi> tags in the text are to be checked for state-changes.
A state-change is signalled whenever a new <gi>mileStone</gi> tag is
found with <att>unit</att> and, optionally, <att>ed</att> attributes
identical to those of the <gi>state</gi> element in question.  The value
for the new state may be given explicitly by the <att>n</att> attribute
on the <gi>mileStone</gi> element, or it may be implied, if the
<att>n</att> attribute is not specified.</p>
 
<p>For example, for canonical references in the form <cited>xx.yyy</cited> where
the <cited>xx</cited> represents the page number in the first edition, and
<cited>yyy</cited> the line number within this page, a reference system
declaration such as the following would be appropriate:
 
<eg><![ CDATA[
 <refsDecl>
   <state ed='first' unit='page' delim='.' length=2>
   <state ed='first' unit='line' length=4>
 </refsDecl>
]]>
</eg>
 
This implies that milestone tags of the form
 
<eg><![ CDATA[
 <mileStone ed='first' unit=page n='II'>
 <mileStone ed='first' unit=line>
]]>
</eg>
 
will be found throughout the text, marking the positions at which page
and line numbers change. Note that no value has been specified for the
<att>n</att> attribute on the second milestone tag above; this implies
that its value at each state change is monotonically increased.
For more detail on the use of milestone tags, see section
<xref target="CORS5">.
<!-- was:  target=P2.232ms> -->
<!-- was:  target=CORSYS5 > -->
<!-- following algorithm should also be moved to CREF --></p>
 
<p>The milestone referencing scheme, though conceptually simple, is not
and cannot be supported by an SGML parser.  Its use places a
correspondingly greater burden of verification and accuracy on the
encoder.</p>
 
<p>The elements discussed in this section are formally defined as
follows:
 
<dtdFrag id="D2254" n="The reference scheme declaration">
<tagDecl tagDoc="REFSDECL">
<tagDecl tagDoc="STEP">
<tagDecl tagDoc="STATE">
</dtdFrag></p>
 
<p>A reference system declaration which applies to more than one text or
division of a text need not be repeated in the header of each such text.
Instead, the <att>decls</att> attribute of each text (or subdivision of
the text) to which the declaration applies may be used to supply a cross
reference to it, as further described in section <xref target="CCAS">.
<!-- was:  target=SP31>. -->
<!-- was:  target=P2.3431>. -->
 
<!></p></div4></div3>
<div3 id="HD55"><head>The Classification Declaration</head>
 
<p>The <gi>classDecl</gi> element is the sixth of the nine optional
subdivisions of the <gi>encodingDesc</gi> element.  It is used to group
together definitions or sources for any descriptive classification
schemes used by other parts of the header.  Each such scheme is
represented by a <gi>taxonomy</gi> element, which may contain either a
simple bibliographic citation, or a definition of the
descriptive typology concerned; the following elements are used
in defining a descriptive classification scheme:
 
<tagList>
<tagDesc tagDoc="CLASDECL">
<tagDesc tagDoc="TAXONOMY">
<tagDesc tagDoc="CATEGORY">
<tagDesc tagDoc="CATDESC">
</tagList>
 
The <gi>taxonomy</gi> element has two slightly different, but related,
functions. For well-recognized and documented public classification
schemes, such as Dewey or other published descriptive thesauri, it
contains simply a bibliographic citation indicating where a full
description of a particular taxonomy may be found.
<eg><![ CDATA[
<taxonomy id=DDC12>
  <bibl><title>Dewey Decimal Classification</title>
    <edition>Abridged Edition 12</edition>
    <!-- etc. -->
  </bibl>
</taxonomy>
]]>
</eg>
 
For less easily accessible schemes, the <gi>taxonomy</gi> element
contains a description of the taxonomy itself as well as an optional
bibliographic citation.  The description consists of a number of
<gi>category</gi> elements, each defining a single category within the
given typology.  The category is defined by the contents of a nested
<gi>catDesc</gi> element, which may contain either a phrase describing
the category, or a <gi>textDesc</gi> element defining it in terms of the
situational parameters discussed in section <xref target="CCAHTD">.  If the
category is subdivided, each subdivision is represented by a nested
<gi>category</gi> element, having the same structure.  Categories may be
nested to an arbitrary depth in order to reflect the hierarchical
structure of the taxonomy.  Each <gi>category</gi> element bears a
unique <att>id</att> attribute, which is used as the target for
<gi>catRef</gi> elements referring to it.
 
<eg><![ CDATA[
 
<taxonomy id=B>
   <bibl>Brown Corpus</bibl>
   <category id=B.A><catDesc>Press Reportage
      <category id=B.A1><catDesc>Daily</category>
      <category id=B.A2><catDesc>Sunday</category>
      <category id=B.A3><catDesc>National</category>
      <category id=B.A4><catDesc>Provincial</category>
      <category id=B.A5><catDesc>Political</category>
      <category id=B.A6><catDesc>Sports</category>
    <!-- ... -->
   </category>
   <category id=B.D><catDesc>Religion
      <category id=B.D1><catDesc>Books</category>
      <category id=B.D2><catDesc>Periodicals and tracts</category>
   </category>
<!-- ... -->
</taxonomy>
]]>
</eg></p>
 
<p>Linkage between a particular text and a category within such a
taxonomy is made by means of the <gi>catRef</gi> element within the
<gi>textClass</gi> element, as described in section <xref
target="HD43">.  Where the taxonomy permits of classification along more
than one dimension, more than one category will be referenced by a
particular <gi>catRef</gi>, as in the following example, which
identifies a text with the sub-categories <q>Daily</q>, <q>National</q>
and <q>Political</q>, within the category <q>Press Reportage</q> as
defined above.
 
<eg><![ CDATA[
 <catRef target="B.A1 B.A3 B.A5">
]]>
</eg></p>
 
<p>The elements discussed in this section are defined as follows:
 
<dtdFrag id="D2255" n="The classification declaration">
<tagDecl tagDoc="CLASDECL">
<tagDecl tagDoc="TAXONOMY">
<tagDecl tagDoc="CATEGORY">
<tagDecl tagDoc="CATDESC">
</dtdFrag></p></div3>
 
<div3 id="HDFSD"><head>The Feature System Declaration</head>
 
<p>The <gi>fsdDecl</gi> element is the seventh of the nine optional
subdivisions of the <gi>encodingDesc</gi> element.  It is used to
associate a <term>feature system declaration</term>  (as defined in
chapter <xref target="FD">) with any analytic <term>feature
structures</term> (as defined in chapter <xref target="FS">) present in
the text documented by this header.</p>
 
<p>It has the following description and attributes:
 
<tagList>
<tagDesc tagDoc="FSDDECL" atts="type fsd">
</tagList>
 
Note that one <gi>fsdDecl</gi> element must be specified for each
distinct type of feature structure used in the markup.  The
<att>fsd</att> element supplies the name of an external entity
containing the actual declaration for that type of feature structure.
This entity will typically be defined in the document type subset for
the document, as in the following example:
 
<eg rend="skel">
<![ CDATA [
<!DOCTYPE TEI.2 PUBLIC "-//TEI P3//DTD Main Document Type//EN"
                       "tei2.dtd" [
   <!-- declare an external entity for the FSD -->
   <!ENTITY myFeatures  SYSTEM 'myfeat.fsd' SUBDOC >
]>
<tei.2>
<!-- ... -->
</tei.2>
]]>
</eg>
 
This associates the name <ident rend="noindex" type="ge">myFeatures</ident>
with an external <code type="kw">SUBDOC</code> entity<note>The <code
type="kw">SUBDOC</code> keyword indicates to an SGML parser that this
entity contains SGML data which must be parsed using some other DTD than
the current one:  in this case, the DTD defined in chapter <xref
target="FD"> rather than the view of the &tei; DTD defined for the
document itself.</note> held in this example within a system file called
<ident rend="noindex" type="file">myfeat.wsd</ident>.  This entity name may
then be specified within a <gi>fsdDecl</gi> element in the header to
inform a processor of the location of the feature system declaration
corresponding to a given type of feature structure used within the text,
as follows:
 
<eg rend="skel">
<![ CDATA [
   <teiHeader>
      <fileDesc> ... </fileDesc>
      <encodingDesc>
           <!-- ... -->
           <fsdDecl type=myA1 fsd=myFeatures>
           <fsdDecl type=myA2 fsd=myFeatures>
           <!-- ... -->
      </encodingDesc>
]]>
</eg>
 
This header would be attached to a text in which feature structures of
types <code type="value">myA1</code> and <code type="value">myA2</code> are
used.</p>
 
<p>Further details and examples of the use of feature structure analyses
and feature system declarations are provided in chapters <xref
target="FS"> and <xref target="FD"> respectively.</p>
 
<p>The <gi>fsdDecl</gi> element is declared as follows:
 
<dtdFrag id="D2256" n="The FSD declaration">
<tagDecl tagDoc="FSDDECL">
</dtdFrag></p></div3>
 
<div3 id="HDMN"><head>The Metrical Declaration Element</head>
 
<p>The <gi>metDecl</gi> element is the eighth of the nine optional
subdivisions of the <gi>encodingDesc</gi> element.  It is used to
document any metrical notation scheme used in the text, as further
discussed in section <xref target="VEME">. It consists either of
a prose description or a series of <gi>symbol</gi> elements.
 
<tagList>
<tagDesc tagDoc="METDECL" atts="pattern">
<tagDesc tagDoc="SYMBOL" atts="value terminal">
</tagList></p>
 
<p>As with other components of the header, metrical notation may be
specified either formally or informally. In a formal specification,
every symbol used in the metrical notation must be documented by a
corresponding <gi>symbol</gi> element; in an informal one, only a brief
prose description of the way in which the notation is used need be
given. In either case, the optional <att>pattern</att> attribute may be
used to supply a regular expression which a processor can use to
validate expressions in the intended notation. The following
constraints apply:
 
<list>
 
<item>if <att>pattern</att> is supplied, any notation used which does
not conform to it should be regarded as invalid</item>
 
<item>if any <gi>symbol</gi> is defined, then any notation using
undefined symbols should be regarded as invalid</item>
 
<item>if both pattern and symbol are defined, then every symbol
appearing explicitly within pattern must be defined</item>
 
<item>symbols may be defined within a <gi>metDecl</gi> element which are
not matched by <att>pattern</att></item>
 
</list></p>
 
<p>As a simple example, consider the case of the notation in which
metrical prominence, foot and line boundaries are all to be encoded.
Legal specifications in this notation may be written for any sequence of
metrically prominent or non-prominent features, optionally separated by
foot or metrical line boundaries at arbitrary points.  Assuming that the
symbol <cited>1</cited> is used for metrical prominence,
<cited>0</cited> for non-prominence, <cited>|</cited> for foot boundary
and <cited>/</cited> for line boundary, then the following declaration
achieves this object:
 
<eg>
<![ CDATA [
<metDecl pattern= '((1|0)+\|?/?)*' >
   <symbol value='1'>metrical promimence
   <symbol value='0'>metrical non-prominence
   <symbol value='|'>foot boundary
   <symbol value='/'>metrical line boundary
</metDecl>
]]>
</eg></p>
 
<p>The same notation might also be specified less formally, as follows:
 
<eg>
<![ CDATA[
<metDecl>
 <p>Metrically prominent syllables are marked '1' and other
    syllables '0'. Foot divisions are marked by a vertical bar,
    and line divisions with a solidus.
 <p>This notation may be applied to any metrical unit, of any
    size (including, for example, individual feet as well as
    groups of lines).
</metDecl>
]]>
</eg>
 
Note that in this case, because the <att>pattern</att> attribute has not
been supplied, no processor can validate <att>met</att> attribute values
within the text which use this metrical notation.</p>
 
<p>For more complex cases, it will often be more convenient to define a
notation incrementally.  The <att>terminal</att> attribute should be
used to indicate for a given symbol whether or not it may be re-defined
in terms of other symbols used within the same notation.  For example,
here is a notation for encoding classical metres, in which symbols are
provided for the most common types of foot.  These symbols are
themselves documented within the same notation, in terms of more
primitive long and short syllables:
 
<eg>
<![ CDATA [
<metDecl pattern='[DTIS3A]+'>
 <symbol value='D' n='dactyl'   terminal=N>-oo
 <symbol value='T' n='trochee'  terminal=N>-o
 <symbol value='I' n='iamb'     terminal=N>o-
 <symbol value='S' n='spondee'  terminal=N>--
 <symbol value='3' n='tribrach' terminal=N>ooo
 <symbol value='A' n='anapaest' terminal=N>oo-
 <symbol value='o'>short syllable
 <symbol value='-'>long syllable
</metDecl>
]]>
</eg>
 
Note here the use of the global <att>n</att> attribute to supply an
additional name for the symbols being documented.</p>
 
<p>For further discussion of this metrical notation and its use in the
encoding of verse, see section <xref target="VEME">.</p>
 
<p>The elements discussed in this section are defined as follows:
 
<dtdFrag id="D2258" n="Metrical Notation Declaration">
<tagDecl tagDoc="METDECL">
<tagDecl tagDoc="SYMBOL">
</dtdFrag></p></div3>
 
<div3 id="HDVAR"><head>The Variant-Encoding Method Element</head>
 
<p>The <gi>variantEncoding</gi> element is the last of the nine optional
subdivisions of the <gi>encodingDesc</gi> element.  It is used to
document the method used to encode textual variants in the text, as
discussed in section <xref target="TCAPLK">.
 
<tagList>
<tagDesc tagDoc="VARENCOD" atts="method location">
</tagList></p>
 
 
<p>Its formal declaration is as follows:
 
<dtdFrag id="DHDVAR" n="Variant-Encoding Declaration">
<tagDecl tagDoc="VARENCOD">
</dtdFrag>
</p></div3></div2>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-default-dtd-file:"~/lib/psgml/p2odd.ced"
sgml-parent-document:("/home/tei/P3/Master/Odds/p2.odd" "TEI.1" "TEXT" "BODY" "DIV1")
sgml-omittag:t
sgml-shorttag:t
End:
-->
<?tei:EOF p2hd5.odd ?>
