<?tei:SOF p2saxr.odd ?>
<!-- $Id: p2saxr.odd,v 1.8 1998/02/05 17:14:35 tei Exp $ -->
<!--*
    **
    * $Log: p2saxr.odd,v $
    * Revision 1.8  1998/02/05 17:14:35  tei
    * make examples parse
    *
    * Revision 1.7  98/02/01  16:52:05  tei
    * change system identifiers to public identifiers
    * fix log keyword
    * normalize SGML
    * 
    * Revision 1.6  98/01/28  11:09:58  cmsmcq
    * LB changes of January 1998
    * 
    * Revision 1.5  1994/04/08  18:54:36  msmcq
    * Last-second fixes for P3
    * 
    * Revision 1.4  1994/03/27  21:47:19  msmcq
    * Correction of typos found by SJ, DB et al.
    * 
    * Revision 1.3  1994/03/16  03:29:41  msmcq
    * Changes as per JL, with some LB and TL.
    * -->
<!-- Latex Probs in this file:
  <q>#CDATA</q>
-->
<!-- Revisions:                                               -->
<!-- 18 jan 98 : LB : fix xref error from Greg Murphy -->
<!-- 7 jan 98 : LB : fix typos (circ in cdata) from MSM -->
<!-- 94-04-08 : MSM : fix a ms close problem?                 -->
<!-- 94-04-08 : MSM : change tagdesc for xref, xptr           -->
<!-- 94-04-08 : MSM : discuss doc, from, to as inherited from xpointer -->
<!-- 94-04-08 : MSM : (not local)                             -->
<!-- 94-03-27 : MSM : remove terminal semicolon from bnf (DB) -->
<!-- 94-03-26 : MSM : typos from HG, DB, SJ                   -->
<!-- 94-03-26 : MSM : disambiguate TERM, Q (into code, ident, -->
<!--                  etc.  Location term keywords are tagged -->
<!--                  as CODE TYPE=TEIKW, nonterminals of the -->
<!--                  grammar as IDENT TYPE=NONTERM           -->
<!-- 94-03-15 : MSM : change ID for FOLLOWING section (dup)   -->
<!-- 94-03-15 : MSM : supply TYPE on all IDENT elems          -->
<!-- 94-03-15 : CMSMcQ : require value for each att in a step -->
<!-- 12 Mar 94 : CMSMcQ : make John Lavagnino's suggested     -->
<!--                      changes, for canonical refs         -->
<!-- 3 feb 94: LB check for funny chars, minor revision of  structure -->
<!-- 93-06-05 : MSM : suppress dot in col 1                   -->
<!-- 93-01-26 : MSM : make adList point to Pointer not Loc    -->
<!-- 93-01-26 : MSM : changes for publication                 -->
<!-- 93-01-21 : MSM : revise thoroughly, add bnf, exx         -->
<!-- 92-12-23 : MSM : strip header                            -->
<!-- Date: Wed, 23 Dec 1992 14:25:57 +0000                    -->
<!-- From: Lou Burnard <lou@vax.ox.ac.uk>                     -->
<!-- To: U35395@UICVM.UIC.EDU                                 -->
<!-- Subject: saxr.odd (5 of 9)                               -->
 
<div2 id="SAXR"><head>Extended Pointers</head>
 
<p>Where the object of a link or pointer element is not contained within
the current document, or where it does not bear an <att>id</att>
attribute, it is not possible to point at it with a <gi>ptr</gi> or
<gi>ref</gi> element, nor to link it directly with a <gi>link</gi>
element, because no IDREF value can be supplied for the
<att>target</att> or <att>targets</att> attribute of these elements.  In
such cases, the encoder must indicate the intended element indirectly by
means of the elements discussed in this section.  These elements
identify their target using a special TEI-defined extended pointer
notation, defined in section <xref target="SAXRS"> below and designed for
compatibility with HyTime.
<note>HyTime is an international standard (ISO 10744) built on SGML.
It provides facilities for representing both static and dynamic
information for processing and interchange by hypertext and multimedia
applications.  See <citation><title> ISO/IEC 10744 Information
Technology --- Hypermedia/Time-based Structuring Language
(HyTime)</title>
([Geneva]:  International Organization for Standardization,
1992)</citation>.</note>
<!-- For discussion of the relation between TEI proposals  -->
<!-- and Hytime, see chapter <xref target=OS>. -->
<!-- ... but not till it gets written ... --></p>
 
<div3 id="SAXR1"><head>Extended Pointer Elements</head>
 
<p>To point or refer to locations in the current or some other document
<emph>without</emph> requiring that the target bear an SGML identifier,
the following elements should be used:
 
<tagList>
<tagDesc tagDoc="XPTR">
<tagDesc tagDoc="XREF">
</tagList>
 
These elements are both members of the element class
<ident type="class">pointer</ident>, and therefore carry the same
attributes as other members of that class, listed above (see section
<xref target="SAPTL">).
 
<!-- adList classDoc=POINTER
        atts="type resp crdate targType targOrder evaluate" -->
 
<!-- do targType and targOrder make much sense here? -->
 
They are also members of the class <ident type="class">xPointer</ident>,
from which they inherit the following attributes:
 
<adList classDoc="XPOINTER" atts="doc from to"></p>
 
<p>Unlike the pointer elements discussed in the previous section, these
elements do not specify their target by means of a <att>target</att>
attribute.  Instead these elements use one or both of the attributes
<att>from</att> and <att>to</att> to delimit a portion of some document
specified by the <att>doc</att> attribute.  In all other respects, these
elements correspond with the elements <gi>ptr</gi> and <gi>ref</gi>
discussed in sections <xref target="COXR">, and <xref target="SAPT">.  Note
that there is no element <gi tei="no">xlink</gi> corresponding with the
<gi>link</gi> element; links can be made both within and between
documents using the same syntax, as further discussed below.</p>
 
<p>The values of the <att>from</att> and <att>to</att> attributes on the
<gi>xptr</gi> and <gi>xref</gi> elements indicate the point or passage
being referred to by showing how to locate it, using one or more special
keywords, as defined below in section <xref target="SAXRS">.  Examples are
given there.</p>
 
<p>The <gi>xptr</gi> and <gi>xref</gi> elements are formally defined as
follows:
 
<dtdFrag id="DSAXR" n="Extended pointers">
<tagDecl tagDoc="XREF">
<tagDecl tagDoc="XPTR">
</dtdFrag></p></div3>
 
<div3 id="SAXRS"><head>Extended Pointer Syntax</head>
 
<p>As noted above, the elements <gi>xptr</gi> and <gi>xref</gi> are used
to represent a link between their own location (the <soCalled>link
origin</soCalled>) and some other location (the
<soCalled>destination</soCalled>), which may or may not be in the same
document.  Software supporting intra- and inter-document links (e.g.
hypertext systems) should provide access from the location of such an
element to the destination.</p>
 
<p>This section defines the allowable values for the attributes
<att>from</att>, <att>to</att>, and <att>doc</att> of the <gi>xptr</gi>
and <gi>xref</gi> elements.</p>
 
<p>An <gi>xptr</gi> or <gi>xref</gi> element with <emph>no</emph>
attributes at all is, by definition, a link to the root (i.e. the
<term rend="noindex">document element</term> --- by default, this is the
<gi>tei.2</gi> element) of the document in which it appears.</p>
 
<p>The <att>doc</att> attribute value must be the name of an entity
declared in the SGML document type declaration.  If only the
<att>doc</att> attribute is given a value, then by definition the
destination is the entire entity named by the <att>doc</att> value.  A
more specific location within another entity must be specified with the
<att>from</att> and the <att>to</att> attributes, as described below.
 
<!-- Removed requirement that FROM and TO both have values.   -->
<!-- Maybe wrongly.  -msm                                     --></p>
 
<p>The <att>from</att> and the <att>to</att> attributes indicate the
specific location pointed at, within the entity named by the
<att>doc</att> attribute (or within the current document, if no
<att>doc</att> value is given).  Their values are referred to below as
<term>location pointer specification</term>s.  When both attributes are
specified, the span pointed at by the element runs from the starting
point of the span indicated by <att>from</att> to the ending point of
the string specified by <att>to</att>.  If the latter precedes the
former in the document, then the pointer is in error and fails.  If only
the <att>from</att> attribute is specified, the <att>to</att> attribute
defaults to the same value; the effect is that the element as a whole
points to the span indicated by the <att>from</att> attribute.  It is a
semantic error to specify a value for <att>to</att> but not for
<att>from</att>.</p>
 
<div4 id="SAXR11"><head>Location Ladders</head>
 
<p>Each location pointer specification consists of a sequence of
<term>location term</term>s, each of which consists of a keyword
specifying a <term>location type</term> followed by one or more
parenthesized parameter lists, each of which specifies a <term>location
value</term> via a list of parameters.  Location types and values, and
the parameters within a location value, must be separated by white space
characters.</p>
 
<p>Using terms borrowed from <term>HyTime</term>, we say that each TEI
location term in a specification provides the <term>location
source</term> for the next, and the entire specification is equivalent
to a <term>location ladder</term>.  By specifying the entire ladder in a
single attribute value, the TEI extended pointer mechanism greatly
reduces the syntactic and processing complexity of hypertextual
pointers.</p>
 
<p>In formal terms:<note place="foot">
<!-- The formal grammar specified in this section is          -->
<!-- reproduced as a unit in the appendix.                    -->
The notation used for this formal grammar is that defined in chapter
<xref target="GR">.</note>
 
<eg rend=syntax>
<![ CDATA [
ladder   ::=  locterm
         |    ladder locterm
]]>
</eg></p></div4>
 
<div4 id="SAXR12"><head>Location Terms</head>
 
<p>The keywords used in location terms are these; references to <q>the
tree</q> mean the tree representing the SGML document hierarchy.
 
<list type="gloss">
 
<label>root</label>
 
<item>points at the root of the target document</item>
 
<label>here</label>
 
<item>points at the location of the pointer</item>
 
<label>id</label>
 
<item>points at an ID within the target document</item>
 
<label>ref</label>
 
<item>gives a <soCalled>canonical reference</soCalled> to a location in
the target document</item>
 
<label>child</label>
 
<item>indicates an element found by descending one level in the tree</item>
 
<label>descendant</label>
 
<item>indicates an element found by descending one or more levels in the
tree</item>
 
<label>ancestor</label>
 
<item>indicates an element found by ascending one or more levels in the
tree</item>
 
<label>previous</label>
 
<item>indicates an element found by traversing the older siblings of the
current location source</item>
 
<label>next</label>
 
<item>indicates an element found by traversing the younger siblings of
the current location source</item>
 
<label>preceding</label>
 
<item>indicates an element found by traversing the entire portion of the
document preceding the current location source</item>
 
<label>following</label>
 
<item>indicates an element found by traversing the entire portion of the
document which follows the current location source</item>
 
<label>pattern</label>
 
<item>specifies a regular expression to be located within the existing
location source</item>
 
<label>token</label>
 
<item>points at one or more <term rend="noindex">tokens</term> in the
character content of the location source</item>
 
<label>str</label>
 
<item>points at one or more characters in the character content of the
location source</item>
 
<label>space</label>
 
<item>points at a location using coordinates in some
(application-defined) n-dimensional space</item>
 
<label>foreign</label>
 
<item>points at a location using some non-SGML method, and gives the
name of the method</item>
 
<label>HyQ</label>
 
<item>points at a location using the HyQ query language defined by ISO
10744 (HyTime)</item>
 
<label>ditto</label>
 
<item>(in the <att>to</att> attribute only) points at the same span as
was indicated by the <att>from</att> attribute</item>
 
</list></p>
 
<p>In formal terms:
 
<eg rend=syntax> <![ CDATA [
locterm ::=   'ROOT'                        // default first location
         |    'HERE'                        // location of the xptr
         |    'ID' '(' NAME ')'             // only one ID allowed.
         |    'REF' '(' characters ')'      // only one ref allowed
         |    'CHILD' steps
         |    'DESCENDANT' steps
         |    'ANCESTOR' steps
         |    'PREVIOUS' steps
         |    'NEXT' steps
         |    'PRECEDING' steps
         |    'FOLLOWING' steps
         |    'PATTERN' regs                // mult patterns allowed
         |    'TOKEN' '(' range ')'
         |    'STR' '(' range ')'
         |    'SPACE' '(' NAME ')' pointpair
         |    'FOREIGN' parms
         |    'HYQ' parms
         |    'DITTO'                       // valid only in TO att.
]]>
</eg>
 
Note that the keywords, though shown here quoted in uppercase, are not
case sensitive.</p>
 
<p>Each location term specifies a location in the target document; this
location may be a single point, more often a span of text (often the
span of a single element) within the target document.  The location
ladder as a whole is interpreted from left to right, and each location
term specifies a location relative to the location specified by the
sequence prior to that point (i.e. to its location source).  Unless
<code type="teikw">here</code> or <code type="teikw">id</code> is specified
as the first location term, the beginning location source is always
<code type="teikw">root</code>.  An empty location sequence thus is the
same as <code type="teikw">root</code> and specifies the entire
destination entity.</p>
 
<p>In general, the search for the location specified by a location term
will be conducted only within its location source (i.e. within the
location already identified by preceding location terms).  There are
however several exceptions.  The terms <code type="teikw">root</code>,
<code type="teikw">here</code>, and <code type="teikw">id</code> all ignore
the location source defined by any preceding terms and therefore make
sense only as the first items in the ladder.  The terms <code
type="teikw">ancestor</code>, <code type="teikw">next</code>, and <code
type="teikw">previous</code> do not ignore the location source, but select
a new span from the adjacent or enclosing portions of the text, and not
from within the location source.  Finally the location terms <code
type="teikw">foreign</code>, <code type="teikw">space</code>, and <code
type="teikw">HyQ</code> are not defined fully here; they may or may not
ignore the existing location source.</p>
 
<p>Some of the location terms make sense only in SGML documents; these
are <code type="teikw">id</code>, <code type="teikw">child</code>, <code
type="teikw">ancestor</code>, <code type="teikw">descendant</code>, <code
type="teikw">previous</code>, <code type="teikw">next</code>, <code
type="teikw">preceding</code>, and <code type="teikw">following</code>.  The
latter six involve traversing the tree representing the SGML document
hierarchy and are most easily understood when their location source is a
single SGML element.  If the location source is not a single SGML
element, the tree-traversal keywords operate upon its beginning
end-point, its <soCalled>front end</soCalled> (in English, this will be
the leftmost point of the location source; in Arabic or Hebrew it will
be the rightmost point).  In this case <code type="teikw">child</code> and
<code type="teikw">descendant</code> have no meaning, since character data
has no descendants in the document tree; the first <code type="teikw">ancestor</code> of such a location source is the element
immediately containing the character data in question, and the siblings
referred to by <code type="teikw">next</code> and <code type="teikw">previous</code> are the other children of that immediately
containing element.</p>
 
<p>The details of each keyword are given below, along with definitions
of their syntax and semantics of their results.  Examples are also
provided.  It is strongly recommended that when IDs are available, they
should be used in preference to the other methods for pointing defined
here.</p>
 
<p>For all keywords, the description assumes that the target document
does in fact contain a span or element which matches the description;
otherwise, the location term has no referent and is said to
<soCalled>fail</soCalled>.  If any location term fails, the entire
pointer fails.  No backtracking or retrying is performed (and indeed for
the most part the location terms are defined as having only one matching
location, so backtracking would in most cases lead to no better result).</p></div4>
 
<div4 id="SAXR1RO"><head>The ROOT Keyword</head>
 
<p>The location term <code type="teikw">root</code> selects the root of
the destination document tree; in SGML terms, this is the
<soCalled>document element</soCalled>.  Since it ignores any existing
location source, the <code type="teikw">root</code> keyword makes sense
only as the first location term in the ladder.  Since <code
type="teikw">root</code> is assumed as the implicit first term in any
ladder, the following two location ladders have the same meaning:
 
<eg rend=syntax> <![ CDATA [
ROOT DESCENDANT (2 DIV1) 
]]>
</eg>
<eg rend=syntax> <![ CDATA [
DESCENDANT (2 DIV1)
]]>
</eg>
<div4 id=SAXR1HE><head>The HERE Keyword</head>
 
<p>The keyword <code type=teikw>here</code> designates the location at
which the pointer element itself is situated; it allows extended
pointers to select items like <q>the paragraph immediately preceding the
one within which this pointer occurs</q>.  Since it ignores any existing
location source, this keyword typically makes sense only as the first
location term in a location specification.
 
<p>To designate <q>the paragraph preceding the current one</q>, the
following location ladder could be used:
 
<eg rend=syntax>HERE ANCESTOR (1 P) PREVIOUS (1 P)</eg>
 
(See below for descriptions of the keywords <code
type=teikw>ancestor</code> and <code type=teikw>previous</code>.)
 
<div4 id=SAXR1ID><head>The ID Keyword</head>
 
<p>The resulting location is the element within the destination entity
whose ID attribute has the value specified as the location value.  The
ID location type typically makes sense only as the <emph>first</emph>
location pair in a location specification, but there is no syntactic
requirement that it be so.
 
<p>For example, the location specification
 
<eg rend=syntax>ID (a27)</eg>
 
chooses the necessarily unique element of the destination entity which
has an attribute of declared value of type ID, whose value is <code
type=value>a27</code>.
 
<div4 id=SAXR1RE><head>The REF Keyword</head>
 
<p>The resulting location is an element which can be found by
interpreting the location value in accordance with document-specific
rules for a <term>canonical reference.</term> Such reference systems,
particularly common in documents of interest to classical and biblical
scholars, must also be defined in the TEI header, using the
<gi>refsDecl</gi> element (see section <xref target=HD54>).  If more
than one element matches the canonical reference, the first one
encountered is chosen.
 
<!-- If blanks or any other non-name characters are required  -->
<!-- within location values, the values must be quoted; use   -->
<!-- of blanks in canonical references is not TEI             -->
<!-- recommended practice.                                    -->
<!-- value is already enclosed in (), quotes unneeded. -msm   -->
 
<p>For example, the location specification
 
<eg rend=syntax>REF (MT.2.1)</eg>
 
chooses the first element of the destination entity which is identified
by the canonical reference <cited>MT.2.1</cited>
 
<div4 id=SAXR1CH><head>The CHILD Keyword</head>
 
<p>The <code type=teikw>child</code> location type specifies an element
or span of character data in the document hierarchy using a location
value which functions as a <term rend=noindex>domain-style</term>
address.  The value is a series of parenthesized steps, separated by
white space.  Each such step represents one level of the hierarchy
within the location source.  Each step may contain one or more
parameters separated by white space and interpreted in order as follows:
 
<list type=ordered>
<item>an instance indicator, which is a signed or unsigned integer or
the special value <code type=kw>ALL</code>
<item>optionally, an expression matching an SGML generic identifier
<item>optionally, one or more pairs of expressions, the first matching
an SGML attribute name and the second matching an SGML attribute value
</list>
 
<p>In formal terms, the location value of <code type=teikw>child</code>
is a series of <ident type=nonterm>steps</ident>:
 
<eg rend=syntax>
<![ CDATA [
steps    ::=  '(' step ')'
         |    steps '(' step ')'
 
step     ::=  instance
         |    instance element
         |    instance element avspecs
 
avspecs  ::=  attribute value
         |    avspecs attribute value
 
]]>
</eg>
 
<!-- alternative grammar, to make last attval optional        -->
<!-- avspecs  ::=  attribute                                  -->
<!--          |    attribute value                            -->
<!--          |    attribute value avspecs                    -->
<!--          ;                                               --></p>
 
<p>Location values of the same form are also used by the keywords
<code type="teikw">descendant</code>, <code type="teikw">ancestor</code>, <code
type="teikw">previous</code>, and <code type="teikw">next</code>; details of
the interpretation may vary from keyword to keyword.</p>
 
<p>If an instance indicator alone is specified, as a number <ident
type="variable">n</ident>, it selects the <ident type="variable">n</ident>th child of the location source.  If the
special value <code type="kw">ALL</code> is given, then <emph>all</emph>
the children of the location source are selected.  If the instance
indicator is specified with following parameters, it selects all, or the
<ident type="variable">n</ident>th, among those children of the location
source which satisfy the other parameters.  If a negative number is
given, the <ident type="variable">n</ident>th child is counted from the
last child of the location source to the first.  The location source
must contain at least <ident type="variable">n</ident> children;<note
place="foot">Strictly speaking, |n| (absolute value of n) children.</note>
if it does not, the <code type="teikw">child</code> term fails.</p>
 
<p>In formal terms, the first parameter of a <ident type="nonterm">step</ident> is an instance indicator, which in turn is
either the special value <code type="kw">ALL</code> or a signed integer:
 
<eg rend=syntax>
<![ CDATA [
instance ::=  'ALL'
         |    signed
 
signed   ::=  NUMBER                        // default sign is +
         |    '+' NUMBER
         |    '-' NUMBER
 
]]>
</eg></p>
 
<p>If a second parameter is given, it is interpreted as an SGML generic
identifier, and only elements of the type indicated will be selected.
For example, the location specification
 
<eg rend=syntax>CHILD (3 DIV1) (4 DIV2) (29 P)</eg>
 
chooses the 29th paragraph of the fourth sub-division of the third major
division of the initial location source.  The location specification
 
<eg rend=syntax>CHILD (3 DIV1) (4 DIV2) (-2 P)</eg>
 
chooses the next-to-last paragraph of the fourth <gi>div2</gi> of the
third <gi>div1</gi> in the location source.</p>
 
<p>Constraint by generic identifier is strongly recommended, because it
makes links more perspicuous and more robust.  It is perspicuous because
humans typically refer to things by type:  as <q>the second section</q>,
<q>the third paragraph</q>, etc.  It is robust because it increases the
chance of detecting breakage if (due to document editing) the target
originally pointed at no longer exists.</p>
 
<p>The generic identifier may be specified as a normal SGML name, as a
(parenthesized) regular expression, or using the reserved values <code
type="kw">#CDATA</code> or <code type="kw">*</code>.  Regular expressions
take the form described below; the location term
 
<eg rend=syntax>CHILD (3 (DIV[123])</eg>
 
matches the third element which has a generic identifier of <code
type="value">div1</code>, <code type="value">div2</code>, or <code
type="value">div3</code>.  If the generic identifier is specified as
<code type="value">*</code>, any generic identifier is matched; this means that
<q>CHILD (2 *)</q> is synonymous with <code type="frag">CHILD (2)</code>.
If the second parameter is <code type="frag">#CDATA</code>, the location
term selects only untagged sub-portions of an element having SGML mixed
content.</p>
 
<p>The location ladder
 
<eg rend=syntax>CHILD (3 #CDATA)</eg>
 
thus chooses the third span of character data directly contained by the
current location source.  If the location source is a paragraph
containing
 
<list type="ordered">
<item>a sentence (A)</item>
<item>an embedded quotation, marked as a <gi>q</gi></item>
<item>another sentence (B)</item>
<item>an embedded note, marked as a <gi>note</gi></item>
<item>another sentence (C)</item>
<item>a second embedded quotation, marked as a <gi>q</gi></item>
</list>
 
where the three sentences A, B, and C are character data enclosed by no
element smaller than the paragraph itself, then <code type="frag">CHILD (3
#CDATA)</code> selects sentence C, while <code type="frag">CHILD
(3)</code> selects sentence B.</p>
 
<p>If specified as a name (i.e. without parentheses), the generic
identifier is case sensitive if and only if the SGML declaration
specifies that generic identifiers are case sensitive (by default they
are not).  If specified as a regular expression, the expression given is
always case sensitive; in the usual case this means the regular
expression should be in uppercase, as in the examples here.</p>
 
<p>In formal terms the second parameter of a <ident type="nonterm">step</ident> is defined thus:
 
<!-- <note place=foot>If regular expressions need not be      -->
<!-- parenthesized, then this grammar and the accompanying    -->
<!-- text must be changed.  Remove this note before           -->
<!-- publication.-MSM</note>                                  -->
 
<eg rend=syntax>
<![ CDATA [
element  ::=  NAME
         |    '#CDATA'
         |    '*'
         |    '(' regular ')'
]]>
</eg>
 
<!-- Am uncertain about definition of 'bear' in next para.    -->
<!-- Alternate:  just include test (a).  This allows us to    -->
<!-- skirt, slightly longer, the open question:  for atts     -->
<!-- like LANG, with well defined TEI rules for implied       -->
<!-- values, is the application supposed to have supplied     -->
<!-- them before the search is made or not?  -msm             -->
<!-- I prefer the alternate myself.  And have edited          -->
<!-- accordingly.  LB                                         -->
 
<!-- <p>If a third parameter is specified, it is interpreted  -->
<!-- as an attribute name, and only elements bearing that     -->
<!-- attribute for which that attribute is defined and which  -->
<!-- satisfy the other constraints will be selected.  An      -->
<!-- element is held to <q>bear</q> an attribute if (a) the   -->
<!-- attribute is defined for that element type and (b) the   -->
<!-- value of the attribute is not <q>IMPLIED</q>.  Like the  -->
<!-- preceding, this parameter may be specified as <q>*</q>   -->
<!-- in the (unlikely) event that an attribute value          -->
<!-- constitutes a constraint regardless of what attribute    -->
<!-- name it is a value for.  The parameter may also be       -->
<!-- specified as a parenthesized regular expression.         --></p>
 
<p>The third and fourth parameters, if given, are interpreted as an
attribute-value pair, and only elements which match that pair in the way
described below will be selected; the fourth and fifth parameters, and
all following pairs of parameters, are interpreted in the same way.
When more than one pair is given, all must be matched.</p>
 
<p>The third, fifth, seventh, etc., parameters are interpreted, if
specified, as attribute names.  Like generic identifiers, attribute
names may be specified as <code type="value">*</code> in location ladders
in the (unlikely) event that an attribute value constitutes a constraint
regardless of what attribute name it is a value for.  The attribute name
parameter may also be specified as a parenthesized regular expression.</p>
 
<p>For example, the location term
 
<eg rend=syntax>CHILD (1 * TARGET *)</eg>
 
selects the first child of the location source for which the attribute
<att tei="no">target</att> has a value.  The location term
 
<eg rend=syntax>CHILD (1 * (TARGET(S?)) *)</eg>
 
will select the first child of the location source for which an
attribute called either <att tei="no">target</att> or <att tei="no">targets</att> has a value.</p>
 
<p>As with generic identifiers, attribute names are case sensitive if
and only if the SGML declaration says they are; regular expressions are
always case sensitive and should usually be uppercased, as shown here.</p>
 
<p>In formal terms, the attribute-name parameter of a tree-traversal
step is defined thus:
 
<eg rend=syntax>
<![ CDATA [
attribute ::= NAME
         |    '*'
         |    '(' regular ')'
]]>
</eg></p>
 
<p>If a fourth, sixth, eighth, etc., parameter is specified, it is
interpreted as an attribute value, and only elements satisfying the
other constraints and also bearing an attribute of the specified name
and value will be selected.  The attribute value may be specified
exactly as in an SGML document; as a consequence, if the attribute value
to be specified contains white space characters, it must be enclosed in
quotation marks.  The attribute value may also be specified as a regular
expression, enclosed in parentheses, or using the two special values
<code type="kw">#IMPLIED</code> and <code type="kw">*</code>.</p>
 
<p>For example, the location specification
 
<eg rend=syntax>CHILD (1 * N 2) (1 * N 1)</eg>
 
chooses an element using the global <att>n</att> attribute.  Beginning
at the location source, the first child (whatever kind of element it is)
with an <att>n</att> attribute having the value <code type="value">2</code> is chosen; then that element's first direct
sub-element having the value <code type="value">1</code> for the same
attribute is chosen.</p>
 
<p>The location specification
 
<eg rend=syntax>CHILD (1 FS RESP ((lanc|LANC)(s|S|ashire|ASHIRE)))</eg>
 
selects the first child of the location source which is an <gi>fs</gi>
element bearing a <att tei="no">resp</att> attribute with the value
<code type="value">lancs</code>, <code type="value">lancashire</code>, <code
type="value">LANCS</code>, or <code type="value">LANCASHIRE</code> (as well
as other possible combinations which are left to the reader's
ingenuity).  If specified with quotation marks or as a regular
expression, the attribute-value parameter is case-sensitive; otherwise
not.
 
<!-- how do I say 'if the att value is #IMPLIED' tho?  --></p>
 
<p>The location specification
 
<eg rend=syntax>CHILD (1 FS RESP #IMPLIED)</eg>
 
selects the first child of the location source which is an <gi>fs</gi>
element for which the <att tei="no">resp</att> attribute has been left
unspecified.  The location ladder
 
<eg rend=syntax>ROOT DESCENDANT (1 (DIV[01234567]) TYPE chapter N 2)</eg>
 
selects the second chapter of a text, regardless of whether chapters are
tagged using <gi>div</gi>, <gi>div1</gi>, <gi>div2</gi>, or some other
text-division element.  It does so by selecting the first text-division
element in the document which is of <att tei="no">type</att> chapter and
has the <att tei="no">n</att> value 2.</p>
 
<p>In formal terms, the attribute-value parameter of a tree-traversal
step is defined thus:
 
<eg rend=syntax>
<![ CDATA [
value    ::=  LITERAL                  // i.e. quoted string.
         |    NAME                     // As for attribute values in
         |    NUMBER                   // document, NMTOKENs need not
         |    NUMTOKEN                 // be quoted
         |    '#IMPLIED'               // No value specified, no default
         |    '*'                      // Any value matches.
         |    '(' regular ')'
]]>
</eg></p></div4>
 
<div4 id="SAXR1DE"><head>The DESCENDANT Keyword</head>
 
<p>If the <code type="teikw">descendant</code> keyword is used, the
location term selects an element or character-data string which is a
descendant of the current location source.  Like <code type="teikw">child</code>, <code type="teikw">descendant</code> takes as a
value a series of one or more parenthesized steps, which may contain the
same four parameters described above.  The set of elements and strings
which may be selected, however, is the set of all descendants of the
location source (i.e. the set of all elements contained by it), rather
than only the set of immediate children.</p>
 
<p>The location specification
 
<eg rend=syntax>ID (a23) DESCENDANT (2 TERM LANG DE)</eg>
 
thus selects the second <gi>term</gi> element with a <att>lang</att> of
<code type="value">de</code> occurring within the element with an
<att>id</att> of <code type="value">a23</code>.  The search for matching
elements occurs in the same order as the SGML data stream; in terms of
the document tree, this amounts to a depth-first left-to-right search.</p>
 
<p>If the instance number is negative, the search is a depth-first
right-to-left search, in which the right-most, deepest matching element
is numbered -1, etc.  The location specification
 
<eg rend=syntax>DESCENDANT (-1 NOTE)</eg>
 
thus chooses the last <gi>note</gi> element in the document, that is,
the one with the rightmost start-tag.</p></div4>
 
<div4 id="SAXR1AN"><head>The ANCESTOR Keyword</head>
 
<p>The <code type="teikw">ancestor</code> location term selects an element
from among the direct ancestors of the location source in the document
hierarchy.  The location value is of the same form as defined for the
<code type="teikw">child</code> and <code type="teikw">descendant</code>
location types.  However, the <code type="teikw">ancestor</code> keyword
selects elements from the list of containing elements or
<soCalled>ancestors</soCalled> of the location source, counting upwards
from the parent of the location source (which is ancestor number 1) to
the root of the document instance (which is ancestor number -1).</p>
 
<p>The location source must have at least as many ancestors as the
absolute value of the instance number specified as the first parameter
of the step.  The <code type="teikw">ancestor</code> type thus may not be
specified as the first component of a location specification, because
the initial location source in effect at that point is the root, which
has no ancestors.</p>
 
<p>For example, the location term
 
<eg rend=syntax>ANCESTOR (1 * N 1) (1 DIV)</eg>
 
first chooses the smallest element properly containing the location
source and having attribute <att>n</att> with value <code type="value">1</code>; and then the smallest <gi>div</gi> element properly
containing it.  The location term
 
<eg rend=syntax>ANCESTOR (1)</eg>
 
chooses the immediate parent of the location source, regardless of its
type or attributes.  The location term
 
<eg rend=syntax>ANCESTOR (1 * LANG fr)</eg>
 
selects the smallest ancestor for which the <att>lang</att> attribute
has the value <code type="value">fr</code>.  The term
 
<eg rend=syntax>ANCESTOR (-1 * LANG fr)</eg>
 
selects the <emph>largest</emph> ancestor for which the <att>lang</att>
attribute has the value <code type="value">fr</code>.  Without the
attribute specification, the term
 
<eg rend=syntax>ANCESTOR (-1)</eg>
 
selects the largest ancestor of the location source and is thus normally
synonymous with the keyword <code type="kw">ROOT</code>.  If the instance
indicator is given as <code type="kw">ALL</code>, then all the ancestor
elements which match the later parameters are selected; since the
largest of these will necessarily include all the others, the value
<code type="kw">ALL</code> is thus synonymous with the value <code
type="value">(-1)</code> when used with <code type="kw">ANCESTOR</code>.
 
Finally, the term
 
<eg rend=syntax>ANCESTOR (1 (DIV[0123456789]?))</eg>
 
chooses the smallest <gi>div</gi> element of any level which contains
the location source.</p></div4>
 
<div4 id="SAXR1PR"><head>The PREVIOUS Keyword</head>
 
<p>The <code type="teikw">previous</code> keyword selects an element or
character-data string from among those which precede the location source
within the same containing element.  We speak of the elements and
character-data strings contained by the same <code type="teikw">parent</code> element as <term>siblings</term>; those which
precede a given element or string in the document are its <term>elder
siblings</term>; those which follow it are its <term>younger
siblings</term>.</p>
 
<p>The instance number in the location value of a <code type="teikw">previous</code> term designates the nth elder sibling of the
location source, counting from most recent to less recent.  The location
ladder
 
<eg rend=syntax>ID (a23) PREVIOUS (1)</eg>
 
thus designates the element immediately preceding the element with an
<att>id</att> of <code type="value">a23</code>.  Negative instance numbers
also designate elder siblings, counting from the eldest sibling to the
youngest.  The location source must have at least as many elder siblings
as the absolute value of the instance number.  If the location source
has at least one elder sibling, then the location term
 
<eg rend=syntax>PREVIOUS (-1)</eg>
 
designates its eldest sibling and is thus synonymous with the ladder
 
<eg rend=syntax>ANCESTOR (1) CHILD (1)</eg>
 
The value <code type="kw">ALL</code> may be used to select the entire
range of elder siblings of an element:  the location ladder
 
<eg rend=syntax>ID (a23) PREVIOUS (ALL)</eg>
 
thus designates the set of elements which precede the element with an
<att>id</att> of <code type="value">a23</code> and are contained by the
same parent.</p></div4>
 
<div4 id="SAXR1NE"><head>The NEXT Keyword</head>
 
<p>The keyword <code type="teikw">next</code> behaves like <code
type="teikw">previous</code>, but selects from the younger siblings of the
location source, not the elder siblings.  The location ladder
 
<eg rend=syntax>ID (a23) NEXT (1)</eg>
 
thus designates the element or string immediately following the element
which has an <att>id</att> of <code type="value">a23</code>.  Negative
instance numbers also designate younger siblings, counting from the
youngest sibling to the location source.  The location source must have
at least as many younger siblings as the absolute value of the instance
number.  If the location source has at least one younger sibling, then
the location term
 
<eg rend=syntax>NEXT (-1)</eg>
 
designates its youngest sibling and is thus synonymous with the ladder
 
<eg rend=syntax>ANCESTOR (1) CHILD (-1)</eg></p></div4>
 
<div4 id="SAXR1PC"><head>The PRECEDING Keyword</head>
 
<p>The <code type="teikw">preceding</code> keyword selects an element or
character-data string from among those which precede the location
source, without being limited to the same containing element.  The set
of elements and strings which may be selected is the set of all elements
and strings in the entire document which occur or begin before the
location source.  (For purposes of the keywords <code type="kw">PRECEDING</code> and <code type="kw">FOLLOWING</code>, elements
are interpreted as occurring where their start-tag occurs.)  The <code
type="kw">PRECEDING</code> keyword thus resembles <code type="kw">PREVIOUS</code> but differs in searching a larger set of strings
and elements; its result is not guaranteed to be a subset of its
location source.</p>
 
<p>The instance number in the location value of a <code type="teikw">preceding</code> term designates the nth element or
character-data string preceding the location source, counting from most
recent to less recent.  The location ladder
 
<eg rend=syntax>ID (a23) PRECEDING (5)</eg>
 
thus designates the fifth element or string before the element with an
<att>id</att> of <code type="value">a23</code>.  Negative instance numbers
also designate preceding elements or strings, counting from the eldest
to the youngest; the ladder
 
<eg rend=syntax>ID (a23) PRECEDING (-5)</eg>
 
thus selects the fifth element or string in the document overall,
assuming that it precedes the element with an <att>id</att> of <code
type="value">a23</code>.  It is thus normally synonymous with
 
<eg rend=syntax>ROOT DESCENDANT (5)</eg>
 
differing only in that it fails if four items or fewer precede element
A23.
 
The location source must have at least as many elder siblings as the
absolute value of the instance number; otherwise, the <code
type="teikw">preceding</code> term fails.
 
The value <code type="kw">ALL</code> may be used to select the entire
portion of the document preceding the beginning of the location source:
the location ladder
 
<eg rend=syntax>ID (a23) PRECEDING (ALL)</eg>
 
designates the entire portion of the document preceding the start-tag
for element A23.</p></div4>
 
<div4 id="SAXR1FW"><head>The FOLLOWING Keyword</head>
 
<p>The keyword <code type="teikw">following</code> behaves like <code
type="teikw">preceding</code>, but selects from the portion of the
document following the location source, not that preceding it.  The
location ladder
 
<eg rend=syntax>ID (a23) FOLLOWING (1)</eg>
 
thus designates the element or string immediately following the element
which has an <att>id</att> of <code type="value">a23</code>.  Negative
instance numbers select elements or strings counting from the end of the
document to the location source.  There must be at least as many
elements or strings following the location source as the absolute value
of the instance number.  If the location source has at least one
following element or string, then the location term
 
<eg rend=syntax>FOLLOWING (-1)</eg>
 
designates the youngest of these and is thus synonymous with the ladder
 
<eg rend=syntax>ROOT DESCENDANT (-1)</eg></p></div4>
 
<div4 id="SAXR1PA"><head>The PATTERN Keyword</head>
 
<p>The <code type="teikw">pattern</code> keyword selects the
<emph>first</emph> place within the location source which matches a
pattern-matching expression included as the location value.  If more
than one location matches that expression, there is no error, but the
second and later matches are ignored.</p>
 
<p>Matching is defined to be case-sensitive, i.e. <cited>abc</cited> is
<emph>not</emph> the same as <cited>ABC</cited>.  The pattern is
expressed as a regular expression in which the following characters have
special meanings, similar to those of many Unix programs (such as
<ident type="prog">grep</ident>) which handle regular expressions:
 
<list id="RECHARS" rend="dl" type="gloss">
 
<label>.</label><item>match any single character (including white
space characters).</item>
 
<label>[ ...  ]</label><item>match any character from the set enclosed
within the brackets.  If, however, the first enclosed character is
<cited>&circ;</cited>, then match any character <emph>not</emph> from
the set enclosed within the brackets.  For example,
<cited>[&circ;aeiou]</cited> would match any character except a, e, i,
o, or u.</item>
 
<label>\</label><item>If the next character is a, d, n, or s, the
expression matches any character from a pre-defined group, as shown
below; otherwise, the next character is to be taken literally, even if
it would otherwise have a special meaning.  The special character
classes are:
<list type="gloss">
<label>\a</label><item>any alphabetic character (as defined in the writing
system declaration)</item>
<label>\d</label><item>any digit (0 through 9)</item>
<label>\n</label><item>any line boundary</item>
<label>\s</label><item>any white-space character (space, tab, record end, record
start)</item>
</list>
Note that although \n for newline is provided, its use is
discouraged.</item>
 
<!-- what DOES this mean? if we find someone using it do we chop  -->
<!-- their hands off? lock them in a room with Michael Hart? or what? -->
 
<label>*</label><item>match zero or more occurrences of the previous
regular expression.</item>
 
<label>+</label><item>match one or more occurrences of the preceding
regular expression.</item>
 
<label>?</label><item>match zero or one occurrences of the preceding
regular expression.</item>
 
<label>&circ</label><item>match the following regular expression only at
the beginning of the location source.</item>
 
<label>$</label><item>match the preceding regular expression only at the
end of the location source.</item>
 
<label>|</label><item>match either the regular expression on the left,
or the one on the right.</item>
 
<label>(...)</label><item>match the regular expression within the
parentheses.  (Parentheses are used to control application of the *, ?,
+, and | operators, etc.)</item>
 
</list></p>
 
<p>For example, the location specification
 
<eg rend=syntax>PATTERN (Chapter.8)</eg>
 
chooses the first instance of the content string <cited>Chapter</cited>
which is followed by any single character and then the digit 8, within
the location source.  Various elements which contain that location could
be selected by following the <code type="teikw">pattern</code> location
term with one or more of other types such as <code type="teikw">ancestor</code> (see above).</p>
 
<p>It is recommended practice to use structure-oriented location types
to specify the destination element as narrowly as possible, and then to
specify a pattern only within that element context.  If element
boundaries are encountered within the location source, however, they are
ignored and have no effect on the pattern matching operation.</p>
 
<p>In formal terms, the location value of the <code type="teikw">pattern</code> keyword is defined thus:
 
<eg rend=syntax>
<![ CDATA [
regs     ::= '(' regular ')'
         |    regs '(' regular ')'
 
regular  ::=  character
         |    '.'                           // match any character
         |    '^' || characters || ']'     // match any char not in list
         |    '[' || characters || ']'      // match any char in list
         |    '\a'                     // match any alphabetic
         |    '\d'                     // match any digit 0-9
         |    '\n'                     // match newline (&#RE;&#RS;)
         |    '\s'                     // match any whitespace character
         |    '\\'                     // match backslash (rev. solidus)
         |    '\' || nonspecial        // match nonspecial character
         |    regular || '*'           // match 0-n of 'regular'
         |    regular || '+'           // match 1-n of 'regular'
         |    regular || '?'           // match 0-1 of 'regular'
         |    '^' || regular           // match at start of loc source
         |    regular || '$'           // match at end of loc source
         |    regular || regular       // match 1st, then 2d regular exp.
         |    regular || '|' || regular // match either 1st or 2d
         |    '(' || regular || ')'    // use parentheses for grouping
 
characters ::= /* empty string */
         |    characters character
 
nonspecial ::= /* any character except a, d, n, or s */
]]>
</eg></p></div4>
 
<div4 id="SAXR1TO"><head>The TOKEN Keyword</head>
 
<p>The <code type="teikw">token</code> keyword selects a sequence of one
or more <term rend="noindex">tokens</term> chosen from within the
character content of the location source, where tokens are counted
exactly as for the corresponding HyTime <code type="kw">tokenloc</code>
form.  The location value must be either a single positive integer, or a
pair of positive integers separated by white space, representing the
first and the last token numbers to be included in the resulting
location.  If two integers are specified, the second must not be less
than the first.  The location source must contain at least as many
tokens as are specified in the location value.</p>
 
<p>This location type should not be used to count across element
boundaries.  It is recommended practice to use structure-oriented
location types to specify the destination element as narrowly as
possible, and then to specify a token location only within that element
context.  If element boundaries are encountered within the location
source, they are ignored.</p>
 
<p>This location type behaves intuitively only for strings containing an
alternating sequence of SGML name-characters and white space; this is
the type of string found, for example, in SGML attribute values of type
IDREFS, such as <code type="value">a21 z a13</code>.
 
<!-- It is not TEI recommended practice to apply TOKENLOC to  -->
<!-- other string types, in part because it would compromise  -->
<!-- interconvertibility with HyTime; but if such counting is  -->
<!-- needed, tokens shall be counted as if all non white space  -->
<!-- characters (such as punctuation) were added to the class of  -->
<!-- name characters.  That is, only white space characters  -->
<!-- separate tokens.< /note>  -->
 
For compatibility with the HyTime standard, all characters not included
in the class of name characters by the current SGML declaration (by
default this includes all punctuation other than the hyphen and full
stop) are treated as white space characters.</p>
 
<p>For example, the location specification
 
<eg rend=syntax>ID (a27) TOKEN (3 5)</eg>
 
chooses the 3rd, 4th, and 5th tokens from the content of the element
whose identifier is <code type="value">a27</code>.  If this element
contained the string <cited>This is _not_ a very good idea</cited>, the
target selected would be <cited>not_ a very</cited>.</p>
 
<p>In formal terms the location value of the <code type="teikw">token</code> and <code type="teikw">str</code> keywords is
defined as a range:
 
<eg rend=syntax>
<![ CDATA [
range    ::=  NUMBER
         |    NUMBER NUMBER
]]>
</eg></p></div4>
 
<div4 id="SAXR1ST"><head>The STR Keyword</head>
 
<p>The <code type="teikw">str</code> keyword identifies a sequence of one
or more <term rend="noindex">characters</term> chosen from within the
character content of the location source, where characters are counted
exactly as for the HyTime <code type="kw">dataloc</code> form with <code
type="frag">quantum=str</code>, which has a corresponding meaning and
usage.  The location value must be either a single positive integer, or
a pair of positive integers separated by white space, indicating the
first and the last characters to be included in the resulting location.
If two integers are specified, the second must not be less than the
first.  The location source must have at least as many characters as are
specified in the larger of the integers.</p>
 
<p>This location type should not be used to count across element
boundaries.  The recommended practice is to use structure-oriented
location types to specify the destination element, and then to specify a
character location only within that element context.  If element
boundaries are encountered, however, within the location source, they
have no effect.</p>
 
<p>Character offsets in an SGML document must be counted not from the
original source file, but from the output of the SGML parser, (the
<term>element structure information set</term> or <term>ESIS</term>).
This is because the rules of SGML allow certain characters to be deleted
or expanded transparently.</p>
 
<p>For example, the location specification
 
<eg rend=syntax>ID (a27) STRLOC (3 5)</eg>
 
chooses the 3rd 4th and 5th characters of the content of the element
having identifier a27.  If this element contained the string <q>This
turned out to be an even worse idea</q>, the result would be the string
<cited>is </cited> (i, s and a space).
 
<!-- Not sure whether or not to keep the following one: -->
<!-- It needs to be checked for consistency with whatever goes -->
<!-- into graphs, figures etc. --></p>
 
<p>In multi-byte character sets it is characters which are counted, not
bytes.  However, in the case of diacritics coded by sequences of bit
combinations rather than having separate code points for every
combination of letter and diacritic, the diacritics are counted.  This
means that the following location ladder may retrieve different strings,
depending on the system character set in use and on the entity
declarations in effect:
 
<eg rend=syntax>
<![ CDATA [
PATTERN (Wagner's\sG&ouml;tterd&aum;mmerung) STR (10 24)
]]>
</eg>
 
In some character sets, where &ouml; and &auml; are encoded as single
characters, it will select the string
<cited>G&ouml;tterd&auml;mmerung</cited>; in others, where they are
encoded with distinct characters for umlaut, a, and o, it will select
the string <cited>G&ouml;tterd&auml;mmeru</cited>, truncating the last
two letters.  If a system-dependent definition is used (containing e.g.
a printer escape sequence), the results are even less predictable.  For
this reason, the <code type="teikw">str</code> keyword must be used with
caution and should be avoided where possible.</p></div4>
 
<div4 id="SAXR1SP"><head>The SPACE Keyword</head>
 
<p>The <code type="teikw">space</code> location term applies to entities
which represent graphical or spatio-temporal data; typically such
entities are not encoded in SGML, but in one of many specialized
graphical formats.  SGML provides standard mechanisms (the NOTATION
declaration and related constructs) for specifying what format such an
entity uses.</p>
 
<p>The location value for <code type="teikw">space</code> consists of two
or three parenthesized parameter lists.  The first contains the name of
the co-ordinate space in use.  The second and third each consist of any
number of signed integers.  The numbers in a parameter list represent
locations along each dimension of a Cartesian co-ordinate space with all
axes orthogonal; the length of the list equals the number of
dimensions/axes of the space (usually, but not inevitably, 2, 3, or 4).</p>
 
<p>If the third parameter list is not specified, the location is the
single point in the co-ordinate space specified by the second parameter
list.  If all three parameter lists are specified, the location is the
rectangular prism defined by treating corresponding items of the second
and third lists as inclusive bounds along each dimension in turn.</p>
 
<p>The mapping from co-ordinates to physical or display space, and the
meaning and ordering of the axes, are not defined by these guidelines.
They should be specified in the TEI header unless they can be determined
by definition from the format in which the referenced entity is known to
be encoded (for example, many graphics formats can only encode locations
in units of pixels, counted in a 3 dimensional left-handed co-ordinate
space).</p>
 
<p>Time may be construed as an axis in addition to any others; when it
is, it is TEI recommended practice that it be positioned last.  The
units used must be defined in the TEI header; it is acceptable in
certain media (such as videodiscs) to use frame numbers as a surrogate
axis for time.</p>
 
<p>For example,
 
<eg rend=syntax>SPACE (2D) (0 0) (1 1)</eg>
 
specifies the location of the unit square tangent to the origin in
quadrant 1 of a common graph.</p>
 
<p>The location value for a <code type="teikw">space</code> location term
is a NAME enclosed in parentheses, followed by a point pair:
 
<eg rend=syntax>
<![ CDATA [
pointpair ::= '(' numbers ')'
         |    '(' numbers ')' '(' numbers ')'
 
numbers  ::=  signed
         |    numbers signed
]]>
</eg>
 
<!-- Changed definition of numbers to from the following,     -->
<!-- which contradicts the prose (NUMBER is unsigned, no?)    -->
<!-- msm                                                      -->
<!-- numbers  ::=  NUMBER                                     -->
<!--          |    numbers NUMBER                             -->
<!--          ;                                               --></p></div4>
 
<div4 id="SAXR1FO"><head>The FOREIGN Keyword</head>
 
<p>The <code type="teikw">foreign</code> keyword takes any number of
parenthesized parameter lists, and is terminated by the end of the
attribute value, or by the next non-parenthesized token, whichever comes
first.</p>
 
<p>The meaning of the <code type="teikw">foreign</code> location term is
not defined by these Guidelines.  It is intended for use in pointing to
special kinds of non-SGML, non-coordinate space data.  That is, it
should be used for making links to data which cannot be specified using
the other mechanisms.  The meaning of any <code type="teikw">foreign</code> location types must be specified in the TEI
header, as a series of paragraphs at the end of the
<gi>encodingDesc</gi> element defined in section <xref target="HD5">.
 
<!-- BUT WHERE? -->
<!-- encodingDesc.  I think. -msm -->
 
If more than one such type is used, it is TEI recommended practice that
the first parameter list to <code type="teikw">foreign</code> be a name
associated with the particular type by documentation in the TEI header.</p>
 
<p>For example, assume that some program uses a proprietary data format
called XFORM, and that the program has supplied an identifier <code
type="value">06286208998</code> for some piece of data it owns.  Then the
location specification
 
<eg rend=syntax>FOREIGN (XFORM) (06286208998)</eg>
 
would be one way of expressing a link to that piece of data.</p></div4>
 
<div4 id="SAXR1HY"><head>The HYQ Keyword</head>
 
<p>The <code type="teikw">HyQ</code> keyword takes a single parenthesized
parameter lists, which contains an expression in the <code
type="teikw">HyQ</code> query language defined by the HyTime standard.
See documentation on HyTime and HyQ for definitions of HyQ expressions.</p></div4>
 
<div4 id="SAXR1DI"><head>The DITTO Keyword</head>
 
<p>The <code type="teikw">ditto</code> keyword is valid only as the first
location term in a ladder, and only within the <att>to</att> attribute
of an extended pointer element.  It designates the location result of
the <att>from</att> attribute on the same element.  Thus in the pointer
 
<eg>
<![ CDATA [
<xptr from='ID (a23) ANCESTOR (1 DIV[0123]) PATTERN (Wagnerian)'
      to='DITTO PATTERN (Liebestod)'>
]]>
</eg>
 
the <att>from</att> attribute designates the first occurrence of the
string <cited>Wagnerian</cited> in the <gi>div</gi> containing the
element with an <att>id</att> of <code type="value">a23</code>.  The
<att>to</att> attribute designates the first occurrence of the string
<cited>Liebestod</cited> which occurs <emph>after</emph>
<cited>Wagnerian</cited>, within the same <gi>div</gi>.  Without the
<code type="teikw">ditto</code> keyword, it would be necessary to repeat
the entire location ladder of the <att>from</att> attribute in the
<att>to</att> attribute, which would be error-prone for complex
expressions.</p></div4></div3>
 
<div3 id="SAXR2"><head>Using Extended Pointers</head>
 
<p>As noted above, when only the <att>from</att> attribute is specified,
the <gi>xref</gi> or <gi>xptr</gi> element points at the span indicated
by <att>from</att>.  When both <att>from</att> and <att>to</att> are
specified, the element points at the span running from the beginning of
the span indicated by the former to the end of the span indicated by the
latter.  To point at the second, third, and fourth paragraphs of the
second chapter (<gi>div1</gi>) in the body of the current document,
therefore, one may specify either of the following:
 
<eg>
<![ CDATA [
<xptr from='DESCENDANT (1 body) CHILD (2 div1) (2 p)'
      to = 'DESCENDANT (1 body) CHILD (2 div1) (4 p)' >
<!-- or equivalently: -->
<xptr from='DESCENDANT (1 body) CHILD (2 div1) (2 p)'
      to = 'DITTO NEXT (2 p)'>
]]>
</eg></p>
 
<p>To point to <q>the <gi>term</gi> occurring in the current
<gi>termEntry</gi> with attribute <att>n</att> = 2</q>, only the
<att>from</att> attribute would be required:
 
<eg>
<![ CDATA [
<xptr from='HERE ANCESTOR (1 TERMENTRY) DESCENDANT (1 TERM N 2)'>
]]>
</eg></p>
 
<p>The following example demonstrates how elements from two different
documents may be combined
 
<eg>
<![ CDATA [
 
<xptr id=X1 doc=doc1 from='id (d1.1)'>
<xptr id=X2 doc=doc2 from='id (d2.1) tree (2 *)'>
 
<ptr id=P1 target='X1 x2'>
 
<link targets='p1 s1 s2' evaluate=all>
]]>
</eg>
 
The first <gi>xptr</gi> indicates the element in doc1 which has
identifier <code type="value">d1.1</code>.  The second indicates the
second subelement of the element in doc2 which has identifier <code
type="value">d2.1</code>.  These two elements are pointed to as a single
item by the <gi>ptr</gi> element and given the identifier <code
type="value">p1</code>.  This aggregation, finally, is linked with two
other elements both in the current document, with identifiers <code
type="value">s1</code> and <code type="value">s2</code>.</p>
 
<p>An extended pointer, as described above, may specify as its target
only a single destination.  Where the intended destination of a link is
an aggregation or alignment of destinations, possibly in separate
documents, an intermediate pointer of some kind must be used, as
described in section <xref target="SAPTIP"> elsewhere in this chapter.
Like any other element, an <gi>xref</gi> and <gi>xptr</gi> may be given
a unique id within the document that contains them.  This id value can
then be supplied as one of the <att>target</att> values for an
intermediate <gi>ptr</gi> or <gi>link</gi> element, to represent
aggregation or linkage respectively.  The <gi>join</gi> element
discussed in section <xref target="SAAG"> may also be used.</p>
 
<p>For example, a modern commentary on an older text must frequently
refer to that text, which might well be encoded in a separate SGML
document.  Some discussions will refer to set of discrete passages in
the older text, and will thus require multi-headed pointers.  In such a
case, the document type declaration must contain a declaration for an
SGML entity containing the older text, which might look something like
this:
 
<eg>
<![ CDATA [
<!-- the 1729 Dunciad Variorum -->
<!ENTITY dunciad system 'dunc1729.tei' >
]]>
</eg>
 
In the commentary itself, reference will be made to this external
document, using <gi>xptr</gi> and <gi>xref</gi> elements.  When the
commentary refers to aggregates of discontiguous passages, <gi>xptr</gi>
elements are used to point to the individual passage, and a <gi>ref</gi>
element may refer to these passages as a group by pointing to the
<gi>xptr</gi>s:
 
<!-- These examples should be pointing at notes and lines in  -->
<!-- the Dunciad which really do refer to Theobald and Curl,  -->
<!-- and it would be nice to have a link for something other  -->
<!-- than a person named; possibly imitations of Vergil vs.   -->
<!-- imitations of Ovid, or references to gluttony vs.        -->
<!-- references to piss vs. references to shit.  I'll work    -->
<!-- on this this evening.                                    -->
<!-- These are not at all exhausting, but at least the line   -->
<!-- numbers given are real ones now.                         -->
 
<!-- Perhaps for P3 or for the case book we can get someone   -->
<!-- to give us a real web from an Intermedia system or       -->
<!-- something, or maybe Elli can reproduce part of Perseus.  -->
 
<eg>
<![ CDATA [
<xptr id='XL2.5'   doc=dunciad from='ID (L2.5)'  >
<xptr id='XN1.48'  doc=dunciad from='ID (N1.48)' >
<xptr id='XN1.68'  doc=dunciad from='ID (N1.68)' >
<xptr id='XN1.104' doc=dunciad from='ID (N1.104)'>
<xptr id='XN1.106' doc=dunciad from='ID (N1.106)'>
 ...
<p>In <ref target='XL2.5 xN1.48 xN1.68 xN1.104 xN1.106'
evaluate=all>the references to Theobald</ref>, Pope's satire
characteristically ...</p>
]]>
</eg>
 
If the same discontiguous target is to be referred to repeatedly, it may
be convenient to give it a single identifier, thus:
 
<eg>
<![ CDATA [
<xptr id='XL2.5'   doc=dunciad from='ID (L2.5)'  >
<xptr id='XN1.48'  doc=dunciad from='ID (N1.48)' >
<xptr id='XN1.68'  doc=dunciad from='ID (N1.68)' >
<xptr id='XN1.104' doc=dunciad from='ID (N1.104)'>
<xptr id='XN1.106' doc=dunciad from='ID (N1.106)'>
<ptr id='THEOBALD' target='XL2.5 xN1.48 xN1.68 xN1.104 xN1.106'>
 ...
<p>In <ref target='THEOBALD' evaluate=all>the references to
Theobald</ref>, Pope's satire characteristically ...</p>
]]>
</eg></p>
 
<p>A hypertext web might associate passages of the text and notes with
the individuals mentioned, the ancient authors imitated, or thematic
content, thus:
 
<eg>
<![ CDATA [
<xptr id='XL2.5'   doc=dunciad from='ID (L2.5)'  >
<xptr id='XN1.48'  doc=dunciad from='ID (N1.48)' >
<xptr id='XN1.68'  doc=dunciad from='ID (N1.68)' >
<xptr id='XN1.104' doc=dunciad from='ID (N1.104)'>
<xptr id='XN1.106' doc=dunciad from='ID (N1.106)'>
<ptr id='THEOREFS' target='XL2.5 xN1.48 xN1.68 xN1.104 xN1.106'>
 
<xptr id='XN2.3'   doc=dunciad from='ID (N2.3)'  >
<xptr id='XN2.46'  doc=dunciad from='ID (N2.46)' >
<xptr id='XN2.54'  doc=dunciad from='ID (N2.54)' >
<xptr id='XN2.66'  doc=dunciad from='ID (N2.66)'>
<xptr id='XN2.78'  doc=dunciad from='ID (N2.78)'>
<xptr id='XN1.104' doc=dunciad from='ID (N1.104)'>
<ptr id='CURLREFS' target='XN2.3 xN2.46 xN2.54 xN2.66 xN2.78 xN1.104'>
 
 <!-- ... -->
<div><head>Individuals Named in the Text</head>
<list type=gloss>
<label id=CURLNAME>Curll, Edmund</label>
<item  id=CURLDESC>A bookseller and publisher ... </item>
 <!-- ... -->
<label id=THEONAME>Theobald, Lewis.</label>
<item  id=THEODESC>Attorney, active also as editor and reviewer ...
</item>
 <!-- ... -->
</list>
 
 <!-- ... -->
<div><head>Ancient Authors Imitated in the Text</head>
<list type=bulleted>
<item id=VIRGIL>Virgil
<item id=HOMER >Homer
<item id=OVID  >Ovid
 <!-- ... -->
</list>
 
<ptr id=CURLL    target='CURLNAME curldesc'>
<ptr id=THEOBALD target='THEONAME theodesc'>
 <!-- ... -->
<linkGrp type=bio>
<link targets='theobald theorefs'>
<link targets='curl     curlrefs'>
 <!-- ... -->
</linkGrp>
<linkGrp type=imitations>
<link targets='virgil   virgrefs'>
<link targets='homer    homerefs'>
 <!-- ... -->
</linkGrp>
]]>
</eg>
</p></div3></div2>
<!-- more, and realler, examples needed -->
<!-- damn straight. -msm                -->
 
 
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-default-dtd-file:"~/lib/psgml/p2odd.ced"
sgml-parent-document:(quote ("/home/tei/P3/Master/Odds/p2.odd" "tei.1" "text" "body" "div1" "div2"))
sgml-omittag:t
sgml-shorttag:t
End:
-->
<?tei:EOF p2saxr.odd ?>
