<?tei:SOF p2stpe.odd ?>
<!-- $Id: p2stpe.odd,v 1.4 1994/04/08 18:54:36 msmcq Exp $ -->
<!-- $Log: p2stpe.odd,v $
# Revision 1.4  1994/04/08  18:54:36  msmcq
# Last-second fixes for P3
#
# Revision 1.3  1994/04/01  16:36:47  msmcq
# changes / fixes during validation of DTD
# -->
<!-- P2STpe :  Parameter Entities in TEI DTDs                 -->
<!-- Revisions:                                               -->
<!-- 94-04-08 : MSM : suppress reference to GFtop             -->
<!-- 94-04-08 : MSM : (it was renamed FTtop some time ago)    -->
<!-- 94-03-31 : MSM : add mention of TEI.singlebase           -->
<!-- 94-03-30 : MSM : suppress ref to lmtop                   -->
<!-- 94-03-30 : MSM : Added RCS id                            -->
<!-- 93-09-14 : MSM : move keyword defs to sep file           -->
<!-- 93-09-11 : MSM : rename teigis.ent as teigis2.ent        -->
<!-- 93-04-07 : MSM : cosmetic changes                        -->
<!--                  supply more info on ISO 8601            -->
<!--                  tag entities as terms (temporarily)     -->
<!-- 3 apr 93 : LB revise for publication                     -->
<!--   removed typo; added bib ref for ISO-date (ta, Domo)    -->
<!-- 93-03-30 : MSM : revise for LB                           -->
<!-- 93-03-16 : MSM : move technoid warning to STov.          -->
<!-- 93-03-06 : MSM : quick check before distribution to tei-tech -->
<!-- 93-03-01 : MSM : extract p2STpe from p2STec              -->
<!-- 93-02-02 : MSM : add dtd fragments                       -->
<!-- 93-02-02 : MSM : merge VM and PC changes                 -->
<!-- 25 Jan 93 : CMSMcQ : first revision for publication      -->
<!-- 21 Oct 92 : CMSMcQ : new id new name quick full draft    -->
<!-- 17 May 92 : CMSMcQ : began draft                         -->
 
<div2 id=STPE><head>Other Parameter Entities in TEI DTDs</head>
 
<!-- point:  you need to know what the pe's are to read the DTDs. -->
<!-- uses of p.e.'s in TEI DTDs:                              -->
<!--         - identify base, toppings                        -->
<!--         - specify groups of attributes common to several -->
<!--           elements                                       -->
<!--         - specify groups of elements which appear in     -->
<!--           content models                                 -->
<!--         - include or exclude each element                -->
<!--         - specify name for each element                  -->
<!-- notion of element class:  common locations or atts       -->
<!-- Major p.e.'s of the TEI DTDs:                            -->
<!--         soup                                             -->
<!--         broth                                            -->
<!--         chunks                                           -->
<!--         p.e.s for bases and toppings                     -->
 
<p>The TEI DTDs use SGML parameter entities for several purposes:
 
<list type=bullets>
<item>to define sets of attributes shared by given classes of elements
<item>to define classes of elements which can occur at the same
locations in content models
<item>to identify what base tag set should be used for a document
<item>to identify what additional tag sets should be included
<item>to include or exclude the declaration of each element
<item>to specify the name of each element
</list>
 
The first two applications of parameter entities are described above in
section <xref target=STEC>.  This chapter describes the other uses of
parameter entities in the TEI DTDs.
 
<p>The parameter entities used to specify which base tag
set and which additional tag sets are to be used in a given document
are listed in section <xref target=STBA>.  Their default definition is
always <q>IGNORE</q>:  the encoder selects the TEI base and additional
tag sets by declaring the appropriate parameter entities with the
entity text <q>INCLUDE</q>.
 
<p>The DTD and entity files are listed in section <xref target=STBA>; if
the standard TEI entities are modified to point at locally developed DTD
files containing local modifications or extensions to the TEI DTDs, the
use of the standard parameter entity names ensures that the modification
will be obvious upon examination of the document's DTD.
 
<p>The following entities are referred to by the main
<ident type=file>tei2.dtd</ident> file to embed portions of the TEI DTDs
or locally developed extensions.
 
<list type=gloss>
<label><ident type=pe>TEI.extensions.ent</ident>
<item>identifies a local file containing
extensions to the TEI parameter entities; see section
<xref target=STOVLO>
<label><ident type=pe>TEI.extensions.dtd</ident>
<item>identifies a local file containing
extensions to the TEI tag set; see section <xref target=STOVLO>
<label><ident type=pe>TEI.elementNames</ident>
<item>identifies a file containing parameter
entity declarations for names of TEI elements; see section
<xref target=STPEGI>
<label><ident type=pe>TEI.keywords</ident>
<item>identifies a file containing parameter
entity declarations for TEI keywords, including the default
declaration (<q>IGNORE</q>) of the marked-section keyword for
each tag set; see section
<xref target=STPEKW>
<label><ident type=pe>TEI.elementClasses</ident> <item>identifies a file
containing definitions of parameter entities used in content models; see
section <xref target=STECOV>
<label><ident type=pe>TEI.singleBase</ident> <item>defined as
<code>INCLUDE</code>
(for normal bases) or <code>IGNORE</code> (for mixed and general base);
used to prevent multiple definitions of the default text structure.
</list>
 
<div3 id=STPEEX><head>Inclusion and Exclusion of Elements</head>
 
<p>The TEI DTDs use marked sections and parameter entity references to
allow users to exclude the definitions of individual elements, in order
either to make the elements illegal in a document or to allow the
element to be redefined, as further described in chapter
<xref target=MD>.
 
<p>Parameter entities used for this purpose have exactly the same name
as the generic identifier of the element concerned.  The default
definition for these parameter entities is <q>INCLUDE</q> but they may
be changed to <q>IGNORE</q> in order to exclude the standard element and
attribute definition list declarations from the DTD.
 
<p>The declarations for the element <gi>p</gi>, for example, are
preceded by a definition for a parameter entity with the name
<ident type=ge rend=noindex>p</ident> and contained within a marked
section whose keyword is
given as <q>%p;</q>:
 
<eg>
<![ RCDATA [
 <!ENTITY % p 'INCLUDE' >
 <![ %p; [
        <!-- element and attlist declaration for p here -->
 ]&nil;]>
]]>
</eg>
 
<p>These parameter entities are defined immediately preceding the
element whose declarations they control; because their names are
completely regular, they are not documented individually in the
reference section of this document.
 
<div3 id=STPEGI><head>Parameter Entities for Element Generic Identifiers</head>
 
<p>In the TEI DTDs, elements are not referred to directly by their
generic identifiers; instead, the DTDs refer to parameter entities which
expand to the standard generic identifiers.
This allows users to rename elements by redefining the appropriate
parameter entity (as described more fully in chapter <xref target=MD>).
Parameter entities used for this purpose are formed
by taking the standard name (generic identifier) of the element and
attaching the string <q>n.</q> as a prefix.  Thus the standard generic
identifiers for paragraphs, notes, and quotations, <gi>p</gi>,
<gi>note</gi>, and <gi>q</gi> are defined by declarations of the
following form:
 
<eg>
<![ CDATA [
 <!ENTITY % n.p    'p' >
 <!ENTITY % n.note 'note' >
 <!ENTITY % n.q    'q' >
]]>
</eg>
 
<p>Since by default parameter entities are case-sensitive, the specific
mix of upper and lower case letters in the standard name must be
preserved in the entity name.
 
<p>The formal declarations of the parameter entities used for generic
identifiers are contained in the
file <ident type=file>teigis2.ent</ident>; since
their names and replacement texts are fully predictable, these parameter
entities are not individually documented in the reference section of
these Guidelines.
The parameter entity <ident type=pe>TEI.elementNames</ident> is
used to embed the file <ident type=file>teigis2.ent</ident> in the DTD.
A full set
of alternate generic identifiers can be substituted for the standard set
by defining <ident type=pe>TEI.elementNames</ident> to point at a
different
file.<note place=foot>It is expected that after completion of the full
text of these Guidelines, the TEI will prepare alternate sets of generic
identifiers in languages other than English.  It should be noted,
however, that in the interests of simplicity parameter entities are
used only for generic identifiers; attribute names, standard attribute
values, and parameter entity names are less easily modified.
</note>
 
<div3 id=STPEKW><head>Parameter Entities for TEI Keywords</head>
 
<p>The TEI uses the following parameter entities to signal
information which cannot be expressed using SGML keywords:
 
<list type=gloss>
<label>INHERITED <item>indicates that an attribute value is inherited
from the enclosing element, if not specified
<label>ISO-date <item>indicates that an attribute value should be a
legal ISO date in the form yyyy-mm-dd (e.g. 1993-06-28).
<label>extptr <item>indicates that an attribute value should be a legal
expression in the TEI extended-pointer notation
</list>
 
In addition, the parameter entities which control the selection of
base and additional tag sets may be regarded as a keyword.
 
<!-- no % for consistency with other p.e. names -->
<p>The parameter entity <ident type=pe>INHERITED</ident> is used
to signal that the default value for an attribute should be inherited
from an enclosing element.
The definition for <ident type=pe>INHERITED</ident> is
the string <q>#IMPLIED</q>; as for all implied defaults, the application
program is responsible for deducing the default attribute value when no
value is specified in the element start-tag.  Since the parameter entity
is resolved by the SGML parser, the application program will see no
difference between attributes whose default is <q>%INHERITED</q> and
those whose default is <q>#IMPLIED</q> --- information about which
attribute values are inherited and which are inferred in some other way
must be built into the application in advance.
 
<p>The parameter entity <ident type=pe>ISO-date</ident> is used to
signal that
the value for an attribute should be an ISO-standard date value; in
this notation,<note>Defined by ISO 8601: 1988,
<!-- < title > Codes for the representation of dates          -->
<!-- and times < /title >                                     -->
<title>Data elements and interchange formats --- Information
interchange ---  Representation of dates and times</title>
([Geneva]:  International Organization for Standardization, 1988).
</note>
a date like <q>September 22, 1968</q> would be written
<q>1968-09-22</q>.  The parameter entity <ident type=pe>ISO-date</ident>
expands to <q>CDATA</q>.
 
<p>The keywords controlling the selection of base and additional tag
sets (described in section <xref target=STBA>) all have the default
value <q>IGNORE</q>; the user can override this by a local declaration,
as described in section <xref target=STIN>.
 
<p>The parameter entities for TEI keywords are included in file
<ident type=file>teikey2.dtd</ident>, which is the default replacement
text for the entity <ident type=pe>TEI.keywords</ident> and is embedded
by the file <ident type=file>tei2.dtd</ident>.
 
<p>The file <ident type=file>teikey2.dtd</ident> has the following
contents:
 
<dtdFrag id=DSTKEYS n='TEI Keywords' file='teikey2.ent'>
 
<commDecl>I.  Declare TEI keywords for data types.</commDecl>
<commDecl>These parameter entities are used as keywords to express
rules or constraints which cannot be fully expressed in SGML; their
expansions show the nearest SGML equivalent.</commDecl>
 
<entDecl entDoc=INHERIT>
<entDecl entDoc=ISODATE>
<entDecl entDoc=EXTPTR>
 
<commDecl>II.  Declare keywords for tag-set selection.</commDecl>
<commDecl>Declare all bases and additional tag sets as 'IGNORE'.  The
user can override this default by declaring the same entity with the
replacement text 'INCLUDE', in the document's DTD subset.</commDecl>
<commDecl>Base tag sets first.</commDecl>
<entDecl entDoc='PRTOP'>
<entDecl entDoc='VETOP'>
<entDecl entDoc='DRTOP'>
<entDecl entDoc='TSTOP'>
<entDecl entDoc='DITOP'>
<entDecl entDoc='TETOP'>
 
<commDecl>Now the mixed bases.</commDecl>
<entDecl entDoc='CBGETOP'>
<entDecl entDoc='CBMXTOP'>
 
<commDecl>Now additional tag sets.</commDecl>
<entDecl entDoc='SATOP'>
<entDecl entDoc='AITOP'>
<entDecl entDoc='FSTOP'>
<entDecl entDoc='CETOP'>
<entDecl entDoc='PHTOP'>
<entDecl entDoc='TCTOP'>
<entDecl entDoc='NDTOP'>
<entDecl entDoc='GDTOP'>
<entDecl entDoc='FTTOP'>
<entDecl entDoc='CCTOP'>
 
</dtdFrag>
 
<p>The relevant portion of the main DTD looks like this:
<dtdFrag id=DSTPEKW n='TEI Keywords'>
<commDecl>We declare and immediately embed the TEI keywords file.
</commDecl>
 
<entDecl entDoc=TEIKW>
<peRef n='TEI.keywords.ent'>
</dtdFrag>
<!-- <entDecl entDoc='LMTOP'>                                 -->
<?tei:EOF p2stpe.odd ?>
