<!-- $Id: p2cr.odd,v 1.7 1998/01/28 11:09:58 cmsmcq Exp $ -->
<!-- $Log: p2cr.odd,v $
# Revision 1.7  1998/01/28  11:09:58  cmsmcq
# LB changes of January 1998
#
# Revision 1.6  1994/04/01  16:19:21  msmcq
# Title on single line (for Script's sake)
#
# Revision 1.5  1994/03/27  16:29:04  lou
# semifinal check
#
# Revision 1.2  1994/02/17  20:29:04  msmcq
# Used John Lavagnino's text.
# -->
<!-- Date: Thu, 10 Feb 1994 13:46:08 +0000                    -->
<!-- From: Lou Burnard <lou@vax.ox.ac.uk>                     -->
<!-- To: U35395@UICVM.UIC.EDU                                 -->
<!-- Subject: surprise surprise  - JL came thro with CR!      -->

<!-- P2.CR : Algorithm for Recognizing Canonical References   -->
<!-- Revisions:                                               -->
<!-- 17 jan 98 : LB refs.decls should be refsDecl passim -->
<!-- 94-03-31 : MSM : title on single line!                   -->
<!-- 94-02-15 : MSM : minor fixes, suppress percnt entity     -->
<!-- 94-02-15 : MSM : remove cover notes                      -->
<!-- 94-02-15 : MSM : Added RCS id                            -->
<!-- 94-02-09 :  JL : completely rewritten                    -->
<!-- 93-04-08 :  LK : scanned and tagged text                 -->
<!-- 93-04-07 : MSM : made file                               -->
<!-- 1993-04-06 : WP : found hard copy of old HD draft        -->

<div1 n=32 id=CR><head>Algorithm for Recognizing Canonical References</head>

<p>When a canonical reference is to be automatically processed
according to this method, the following occurs:
<list type=ordered>
<item>The reference is analysed into a series of component
targets, using the <att>delim</att> and <att>length</att>
attributes on the <gi>step</gi> elements within the relevant
<gi>refsDecl</gi>, as described below. The target from the first
<gi>step</gi> element is made available for use in the
subsequent pointer processing as %1, that from the second
as %2, and so on. The number of targets N must be noted,
as it will be used in later steps of the algorithm. (Targets
with numbers greater than N may be referenced, but they will be
null strings.)

<item>Starting at the root of the tree (i.e. the <gi>text</gi>
element, for a TEI-conformant document), a search is made
following the specifications of the pointer in the first
<gi>step</gi> element: its <att>from</att> and <att>to</att>
attributes are processed exactly as would be done with an
<gi>xptr</gi> element.

<item>If there are more targets to be located, the search
continues by following the pointer specifications in the next
<gi>step</gi> element, using as location source the span located
by the previous <gi>step</gi>. Except for this special location
source, the processing is still identical to that done for an
<gi>xptr</gi> element. (Note that this does not prevent an
expansion of the location source at any step, either by using
keywords such as <att>previous</att> which search outside the
location source, or by an explicit return to <att>root</att>.)

<item>When N <gi>step</gi> elements have been processed, the
search is complete. The final result of the reference is a point
or span of text, as with extended pointers.

</list>
Note that there is no backtracking or other attempt at recovery
if a pointer fails. It is instead possible to design the
pointers so that backtracking is not necessary: see the final
example below.
</p>
<p>When analyzing a reference into component targets, the following
procedure is adopted for each <gi>step</gi> element that is
used:
<list type=ordered>

<item>If only the <att>length</att> attribute is specified,
exactly that number of characters is taken from the reference.
Entity references are resolved before characters are counted.
(This implies that references containing entity references may
behave differently on different systems.)

<item>If only the <att>delim</att> attribute was specified,
every character up to the next occurrence of the specified
delimiter is taken from the reference, and the delimiter itself
is removed.

<item>If both <att>length</att> and <att>delim</att> attributes
are specified, a test is made for the presence of the delimiter
in the reference string immediately following the specified
number of characters; if this test fails, the reference fails.

<item>If neither <att>length</att> nor <att>delim</att>
attribute is specified, the remainder of the reference string is
taken. This should happen only for the last <gi>step</gi> in a
<gi>refsDecl</gi>.

<item>The number of components resulting from this procedure
must not exceed the number of steps in the associated
declaration, but may be less than it. (For example, a long poem
might be divided into cantos and lines, but a reference can
point to either a line in a canto or to a whole canto; a
reference to a whole canto would not require the <gi>step</gi>
for the line number.)

</list>
</p>
<p>Here is an example of how a reference system for an encoding of
the Bible could be specified:
<eg>
<![ CDATA [
<refsDecl>
 <step refunit="book" delim=" "
       from="CHILD (1 DIV N %1)"     to="DITTO">
 <step refunit="chapter" delim=":"
       from="CHILD (1 DIV N %2)"     to="DITTO">
 <step refunit="verse" delim=""
       from="CHILD (1 DIV N %3)"     to="DITTO">
</refsDecl>
]]>
</eg>
With this reference declaration, a canonical reference of the
form <q>Matt 5:7</q> is processed by first searching for the
<gi>div</gi> subelement of the <gi>text</gi> element with an
<att>n</att> attribute having value <code>Matt</code>; then searching
within that <gi>div</gi> element for a <gi>div</gi> subelement
with an <att>n</att> attribute having value <code>5</code>; and
finally for a further nested <gi>div</gi> element numbered
<code>7</code>. This example assumes that the unnumbered <gi>div</gi>
elements nevertheless follow a predictable hierarchy: the first
level is always for books, the second for chapters, and the
third for verses. The following reference declaration would
allow intermediate <gi>div</gi> elements of any sort, because it
would search at each step not only for the right <att>n</att>
attribute but also for a <att>type</att> attribute identifying
the structural type of the division:
<eg>
<![ CDATA [
<refsDecl>
 <step refunit="book" delim=" "
       from="DESCENDANT (1 DIV N %1 TYPE BOOK)"     to="DITTO">
 <step refunit="chapter" delim=":"
       from="DESCENDANT (1 DIV N %2 TYPE CHAPTER)"  to="DITTO">
 <step refunit=verse delim=""
       from="DESCENDANT (1 DIV N %3 TYPE VERSE)"    to="DITTO">
</refsDecl>
]]>
</eg>

<p>Other reference systems depend on markers such as page and line
numbers which do not correspond to structural divisions of the
text. These will typically be marked in the text by milestone
elements which identify single points in the text, rather than
by structural elements which contain the portion of the text to
be located. It is then necessary to construct extended pointers
in the reference declaration that can locate both the start and
the end of any segment. Here is a reference declaration for a
work whose reference system consists of page and line numbers:
for example, <q>93.3</q>.
<eg>
<![ CDATA [
<refsDecl>
 <step refunit=page delim="."
       from="FOLLOWING (1 PB N %1)"
       to="FOLLOWING (1 PB)">
 <step refunit=line delim=""
       from="FOLLOWING (1 LB N %2)"
       to="FOLLOWING (1 LB)">
</refsDecl>
]]>
</eg>
To locate the specified page, the application must first search
for the first <gi>pb</gi> element with <att>n</att> equal to
<code>93</code>. It must then find the end of that page, which it does
by searching for the next <gi>pb</gi> element after that for the
start of page 93; this should mark the start of page 94. A
similar procedure is used within the page to find the
<gi>lb</gi> elements that mark the start and end of the desired
line.
</p>
<p>A reference system may combine elements of the last two
approaches: a reference system based on line numbers is normally
used for early English plays, but because such plays often
combine prose and verse the line numbers sometimes refer to
structural elements (for verse passages) and sometimes to
arbitrary typographical boundaries (for prose). One could simply
fill the entire text with milestones, even in the verse passages
which do not require them; but a reference declaration can also
be constructed which requires no superfluous elements. Here is
such a declaration for a collection of plays, and for canonical
references of the form <q>Changeling 1.2.44</q>.
<eg>
<![ CDATA [
<refsDecl>
 <step refunit=work delim=" "
       from="DESCENDANT (1 TEXT N %1)"
       to="DITTO">
 <step refunit=act delim="."
       from="CHILD (1 DIV1 N %2)"
       to="DITTO">
 <step refunit=scene delim="."
       from="CHILD (1 DIV2 N %3)"
       to="DITTO">
 <step refunit=line delim=""
       from="FOLLOWING (1 (L|LB) N %4)"
       to="FOLLOWING (1 (L|LB))">
</refsDecl>
]]>
</eg>
Instead of using the CHILD or DESCENDANT keywords to locate the
<gi>l</gi> elements in verse passages, we use FOLLOWING, which
works to locate <gi>lb</gi> elements as well.
</p>
<p>The algorithm also allows ambiguity in the reference, as a
substitute for requiring backtracking in the processing.
Consider the following reference declaration for a text
containing several works:
<eg>
<![ CDATA [
<refsDecl>
 <step refunit=work delim=" "
       from="DESCENDANT (ALL TEXT N %1)" to="DITTO">
 <step refunit=book delim="."
       from="CHILD (1 DIV1 N %2)"        to="DITTO">
 <step refunit=poem delim="."
       from="CHILD (1 DIV2 N %3)"        to="DITTO">
 <step refunit=line delim=""
       from="CHILD (1 L N %4)"           to="DITTO">
</refsDecl>
]]>
</eg>
Given the canonical reference <code>Amores I.2</code>, the application
will first search for all <gi>text</gi> elements whose
<att>n</att> attribute has the value <code>Amores</code>. This creates
a location source for the second step consisting of one or more
<gi>text</gi> elements, possibly discontiguous; at the second
step, all the <gi>div1</gi> elements numbered <code>I</code> within
those <gi>text</gi> elements are selected. At the third, the
contained <gi>div2</gi> elements numbered <code>2</code> are selected,
and the search ends because the reference string is exhausted:
it points to a whole poem, not to a single line. This reference
declaration is designed for use with a text that contains
several works, some of which might have the same name, so that
at the first step it is not adequate to search merely for the
first <gi>text</gi> called <code>Amores</code>. It may be that several
works called <code>Amores</code> exist but only one has a book
numbered <code>I</code>, so that at the second step the location
source narrows down to the one work desired. In other approaches
to this problem, the works called <code>Amores</code> would be treated
one at a time, and if one turned out not to be the one desired
backtracking to previous steps of the search would be required;
this reference-processing method uses composite location sources
instead to eliminate the need for backtracking.
</p>



             <!-- 32 Canonical Refs -->
<!>
</div1>

