[Mirrored from: http://www.textuality.com/sgml-erb/WD-xml-link.html]

W3CWD-xml-link-970305

Hypertext Links in XML

W3C Working Draft March-5-97

This version:
Previous versions:
Latest version:
Editors:
Tim Bray (Textuality) <tbray@textuality.com>
Steve DeRose (EBT/Inso) <sjd@ebt.com>

Status of this memo

This is a W3C Working Draft for review by W3C members and other interested parties. It is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". A list of current W3C working drafts can be found at http://www.w3.org/pub/WWW/TR.
Note: Since working drafts are subject to frequent change, you are advised to reference the above URL, rather than the URLs for working drafts themselves.
This work is part of the W3C SGML Activity (for current status, see http://www.w3.org/pub/WWW/MarkUp/SGML/Activity).


Abstract

This document specifies a simple set of constructs that may be inserted into XML documents to describe links between objects. It is a goal to use the power of XML to create a structure that can describe both the simple unidirectional hyperlinks of today's HTML, as well as more sophisticated multi-ended, typed, self-describing links.


Hypertext Links in XML Version 1.0 INITIAL DRAFT

Hypertext Links in XML

Version 1.0 INITIAL DRAFT

5 March 1997
This draft is intended for public discussion.

Table of Contents

1. Introduction
    1.1 Origin and Goals
    1.2 Relationship to Existing Standards
    1.3 Terminology
    1.4 Types of link types
2. Link Recognition
    2.1 Operational Issues Concerning Link Recognition
3. Linking Elements
    3.1 Information Associated With Links
    3.2 Extended link
    3.3 Simple Links
4. Link Behavior
    4.1 The SHOW Axis
    4.2 The ACTUATE Axis
5. Addressing
    5.1 HREFs and Reference Types
    5.2 Location Source
    5.3 SGML Reference Types
    5.4 URL Reference Types
    5.5 TEI Locator Reference Types
    5.6 Query Reference Types
6. Extended Link Groups
    6.1 Identifying Extended Link groups
    6.2 LINKS and LINKSET Elements

Appendices

A. The TEI extended pointer syntax
            A.1.1.1 Location Ladders
            A.1.1.2 Location Terms
            A.1.1.3 The ROOT Keyword
            A.1.1.4 The HERE Keyword
            A.1.1.5 The ID Keyword
            A.1.1.6 The CHILD Keyword
            A.1.1.7 The DESCENDANT Keyword
            A.1.1.8 The ANCESTOR Keyword
            A.1.1.9 The PREVIOUS Keyword
            A.1.1.10 The NEXT Keyword
            A.1.1.11 The PRECEDING Keyword
            A.1.1.12 The FOLLOWING Keyword
            A.1.1.13 The TOKEN Keyword
            A.1.1.14 The SPACE Keyword
            A.1.1.15 The FOREIGN Keyword
B. Production note
C. W3C SGML Working Group and Editorial Review Board
    C.1 W3C SGML Working Group
    C.2 W3C SGML Editorial Review Board

1. Introduction

This document specifies a set of constructs which may be inserted in XML documents to describe links between objects (the objects may or may not be XML). A link, as the term is used here, is a relationship which is asserted to exist between two or more data objects or portions of data objects. This specification is concerned with the syntax used to assert link existence and describe link characteristics. The existence of an implicit unasserted relationship, for example that of of one word to the next, or from a word to its entry in an on-line dictionary, is not considered a link here. Obviously this does not cover all the useful kinds of links, and there is no intent, in this specification, either to provide machinery for all such types, nor to preclude applications using the XML linkage machinery from also using other more elaborate mechanisms.

The existence of links is asserted by the presence of elements contained in XML documents. They may or may not reside at the locations of, or in the same documents with, the objects which they serve to connect.

1.1 Origin and Goals

This specification is part of the overall XML effort, on which see .... It aims to provide an effective yet compact structure for representing links that can be in documents or external to them, that can have multiple typed locators, indirection, and precise specification of resource locations in all kinds of data. It also aims to represent the abstract structure and significance of links, leaving formatting issues to stylesheets or other mechanisms as far as practical.

1.2 Relationship to Existing Standards

Three standards have been especially influential:

  1. HTML: Defines several SGML element types that represent links, as well as popularizing a location specifier type, the URL, mainly focused on pointing to entire data objects, though with some provision for linking to elements with IDs, regions in graphics, and so on.
  2. HyTime: Defines location specifier types applicable to all kinds of data, as well as in-line and out-of-line link structures and some semantic features including traversal control and placement of objects into a display or other space.
  3. Text Encoding Initiative: Provides a formal syntax for location specifiers for structured data, graphics, and other data, and structures for creating links and link collections out of them.

Many other linking systems have also informed this design, including Dexter, MicroCosm, and InterMedia.

1.3 Terminology

The following basic terms apply in this document. (figure to be inserted)

  1. resource: In the abstract sense, an addressable unit of information or service which is participating in a link. Examples include files, images, documents, programs, and query results. Concretely, anything which happens to be reachable by the use of a locator in some linking element. In principle, every piece of data may be a resource.
  2. linking element: An element which asserts the existence and describes the characteristics of a link.
  3. locator: A character string appearing in a linking element which may be used to locate a resource. This may be as simple as a URL, ID, or query, or may be a complex chain of relative pointers that eventually lead to a collection of discontinuous data portions that together make up the entire resource.
  4. label: A caption associated with a resource, suitable for showing users as a means of explaining the significance of the part played in the link by that resource.
  5. traversal: The action of using a link; that is, of accessing another resource from an initial resource. Traversal may be initiated by a user action (commonly initiated by clicking on a displayed portion of a linking element) or occur under program control.
  6. multi-directional link: A link that can be traversed starting at more than one of its resources. Note that being able to "go back" after following a one-directional link does not make the link multi-directional.
  7. in-line link: A link whose representation occurs right at one of its resources. HTML <A>, HyTime clink, and TEI <XREF> are all examples of in-line links. Such links are inherently one-directional, because there is nothing at the other end to indicate a link exists.
  8. out-of-line link: A link whose representation does not occur at one of its resources (except perhaps by chance). Such links only make sense given a notion like link groups, which instruct applications where to look for links. Nevertheless, out-of-line links are required to support multi-directional traversal and for creating links with resources which can be traversed starting from read-only data objects.

1.4 Types of link types

Many papers have been written on how to categorize links by type. This specification provides ways to state a link's type along several axes, but only provides a standard vocabulary for the first kind of typing, namely link relationships. The vocabulary of link types can be extended by creating sub-types at all levels.

  1. link relationships: Links express various kinds of relationships between the data objects or portions they connect, in terms of conceptual significance to the author and user. Some links may be criticisms, others add support or background, while others have a very different meaning such as providing access to demographic information about a data object (its author's name, version number, etc), or to navigational tools such as index, glossary, and summary.
  2. link topology: In-line and out-of-line links differ in their structure, as do links involving varying numbers of resources.
  3. locator language: Linking elements commonly differ in what formal language they specify locators. Different locators of the same linking element may use different languages.
  4. formatting: Links may be presented in a variety of ways. The discussion of this area is complicated by the fact that link formatting and link behavior are inextricably linked. This specification does not discuss, nor provide mechanisms for, the provision or use of link formatting information.
  5. link behavior: Links may have a wide variety of effects when traversed, such as opening, closing, or scrolling windows or panes; displaying the data from various resources in various ways; testing, authenticating, or logging user and context information; executing various programs. Ideally, link behavior should be determined by a semantic specification based on link types, resource roles, user circumstances, and other factors; just as element formatting is determined by a stylesheet based on element type, context, and other factors.

2. Link Recognition

The existence of a link is asserted by a linking element. These must be recognized reliably by software in order to provide appropriate display and behavior. XML linking elements are recognized based on the use of a specially reserved attribute named XML-LINK. Possible values are LINK, XLINK, LOCATOR, XLG, and XLD, signalling in each case that the element in whose start-tag the attribute appears is to be treated as an element of the indicated type, as described in this specification.

An example of such a link:

<A XML-LINK="LINK" HREF="http://www.w3.org/">The W3C</A>

2.1 Operational Issues Concerning Link Recognition

There are two distinct mechanisms that may be used to associate the XML-LINK attribute with a linking element. The simplest is to provide it explicitly, as in the example above. However, this practice is verbose, and would be not only cumbersome but wasteful of network bandwidth in the case where there are large numbers of linking elements. Fortunately, XML's facilities for declaring default attribute values can be used to address this problem. For example, suppose one wished to declare the "A" element to be an XML LINK. The following would accomplish this:

<!ATTLIST A XML-LINK CDATA #FIXED "LINK">

The declaration above is simple. The decision of where to place it, however, must be made with care. Such a declaration may be placed in either the external or internal subsets of the Document Type Declaration. However, in a valid XML document, the declaration cannot be placed in both subsets, because for compatibility with SGML, XML forbids the use of more than one attribute list declaration for an element type.

Since it is often expensive and unnecessary for a network client to download the external DTD subset, it would seem that the natural place for the XML-LINK declaration is in the internal subset, which is included in the data transmitted over the network. This would require that to maintain validity, the declaration would need to be removed from the external subset. In practical terms, the maintenance of a DTD which is contained mostly in the external subset, but a small portion of which must appear separately in the internal subset of each document to be transmitted over the network, would be an onerous administrative task.

This conflict between administrative simplicity and document validity is, in the long run, not acceptable. It may soon be resolved by a change to the SGML standard that would allow multiple attribute list declarations per element type; in this case, the XML-LINK attribute could safely be declared in the internal subset without regard to whether it also appears in the external subset.

However, this change to SGML may end up not being made; in which case, this specification will be expanded to provide another technique for declaring which element types are to be treated as XML linking elements, without the overhead of attaching attributes to them every time they appear.

3. Linking Elements

This specification defines two types of linking elements. First, a simple link (LINK), which is always in-line and one-directional, very like the HTML <A> element. Second, a much more general extended link (XLINK) which is out-of-line and may be used for multi-directional links, links into read-only data, and so on.

3.1 Information Associated With Links

This specification describes a variety of information that may be (and in some cases is required to be) associated with linking elements:

Role
Every link has a role, a string used to identify to the application program the meaning of the link. Furthermore, each resource participating in a link may be given its own role. The ROLE attribute is used for both link and resource roles. A set of pre-defined link roles is included in this specification. A sub-role may be created by appending "." and the sub-role name. This process may be repeated in order to create role hierarchies.
Resource
Every locator must identify a resource in some fashion. This is done with a combination of attributes (HREF, HRTYPE, LOCSRC, IMPLIED-LOCSRC) as described in the Addressing section of thius specification.
Label
Every locator may be associated with label in the TITLE attribute. This specification does not require that applications make any particular use of the label.
Behavior
The SHOW and ACTUATE attributes may be used for an author to communicate general policies concerning the traversal behavior of the link; this specification defines a small set of policies for this purpose. The BEHAVIOR attribute may be used to communicate detailed instructions for traversal behavior; this specification does not constrain the contents, format, or meaning of this attribute.

3.2 Extended link

A extended link can involve any number of resources, and need not be co-located with any of them. An application may be expected to provide traversal between all of them (subject to semantic constraints outside the scope of this paper). The key issue with extended links is how to manage and find them, since they do not necessarily co-occur with any of their resources, and often are located in completely separate documents. This process is discussed under Link Groups below.

A extended link's locators are contained in child elements of the linking element, each with its own set of attributes. In the following declaration of the XML the extended link, note that the element types do not need to be those given, since the linking element will be recognized based on the XML-LINK attribute:

<!ELEMENT XML-XLINK   (#PCDATA | XML-LOCATOR)*>
<!ELEMENT XML-LOCATOR ANY>
<!ATTLIST XML-XLINK 
          XML-LINK       CDATA                 #FIXED "XLINK"
          ROLE           CDATA                 #IMPLIED
          LOCSRC         CDATA                 #IMPLIED
          HRTYPE         CDATA                 "URL"
          IMPLIED-LOCSRC (REFERRER|DOCELEM)    "DOCELEM"          
          TITLE          CDATA                 #IMPLIED
          BEHAVIOR       CDATA                 #IMPLIED        
          SHOW           (INCLUDE|REPLACE|NEW) "REPLACE"
          ACTUATE        (AUTO|USER)           "USER"
>
<!ATTLIST XML-LOCATOR
          XML-LINK CDATA                 #FIXED "LOCATOR"
          ROLE     CDATA                 #IMPLIED
          HREF     CDATA                 #REQUIRED
          HRTYPE   CDATA                 "URL"
          TITLE    CDATA                 #IMPLIED
          BEHAVIOR CDATA                 #IMPLIED        
          SHOW     (INCLUDE|REPLACE|NEW) "REPLACE"
          ACTUATE  (AUTO|USER)           "USER"
>

3.3 Simple Links

Simple links are very much like HTML <A> or TEI <XREF> elements, but with more general reference capabilities. A simple link may contain only one locator; thus there is no necessity for a separate child element, and the locator attributes are attached directly to the linking element. The location where the linking element is placed is not required to act as a resource; that is to say, there is no requirement that this location can be reached from the explicit resource, though applications are free to provide that capability if they have a means of knowing that the linking element exists.

Once again, in the following declaration, the linking element type need not be XML-LINK:

<!ELEMENT XML-LINK ANY>
<!ATTLIST XML-LINK
          XML-LINK       CDATA                 #FIXED "LINK"
          ROLE           CDATA                 #IMPLIED
          HREF           CDATA                 #REQUIRED
          HRTYPE         CDATA                 "URL"
          LOCSRC         CDATA                 #IMPLIED
          IMPLIED-LOCSRC (REFERRER|DOCELEM)    "DOCELEM"          
          TITLE          CDATA                 #IMPLIED     
          BEHAVIOR       CDATA                 #IMPLIED
          SHOW           (INCLUDE|REPLACE|NEW) "REPLACE"
          ACTUATE        (AUTO|USER)           "USER"
>

4. Link Behavior

Linking elements assert the existence of links. The traversal of a link requires the use of one or more locators to access and process the corresponding resources.

This specification provides a mechanism for the authors of linking elements to signal their intentions as to the timing and effects of traversal. These intentions can be expressed along two axes, labeled SHOW and ACTUATE. These are used to express policies rather than mechanisms; programs which are processing links in XML documents are free to devise their own mechanisms, best suited to the user environment and processing mode, to implement the requested policies.

In many cases, there will be a requirement for much finer control over the details of traversal behavior; existing hypertext software typically provides such control. Such fine control of link traversal is outside the scope of this specification; however, the BEHAVIOR attribute is provided as a standard place for authors to provide, and in which programs should look for, such detailed behavioral instructions.

4.1 The SHOW Axis

The SHOW attribute is used to express a policy as to the context in which a resource that is traversed to should be displayed or processed. It may take one of three values:

INCLUDE
directs that upon traversal of the link, the indicated resource should be embedded, for the purposes of display or processing, in the body of the resource where the traversal started.
REPLACE
directs that upon traversal of the link, the indicated resource should, for the purposes of display or processing, replace the resource where the traversal started.
NEW
directs that upon traversal of the link, the indicated resource should be displayed or processed in a new context, not affecting that of the resource where the traversal started.

4.2 The ACTUATE Axis

The ACTUATE attribute is used to express a policy as to when traversal of a link should occur. It may take one of two values:

AUTO
directs that the link should be traversed when encountered, and that the display or processing of the resource where the traversal started is not considered complete until this is done.
USER
directs that the link should not be traversed until there is an explicit external request for this to happen.

5. Addressing

Links can involve many kinds of data as resources:

  1. documents: Entire data objects such as files in any representation, can be resources.
  2. nodes: Many documents have a well-defined structure of nodes, such as paragraphs in a flat ASCII file, elements in an SGML document, virtual objects in a VRML or vector-graphic model, and so on. Some such nodes may have unique names, identifiers, or serial numbers; other may be reachable by a scan of the document, such as walking down a tree by child numbers. Any such nodes can be resources.
  3. regions: Many documents have a normative rendered form for two-dimensional display such as on paper or screens. Any point, rectangle, or other region in such a form can be a resource. For some data such as bitmapped images, the rendered form may be the only one of substantial interest, while for other data such as an online book the rendered form may be completely transient.

Note also that there is no requirement that a resource be a singular data object; there is sufficient opacity in addressing methods that a single locator might in fact address multiple data objects, which together would be considered a resource.

A special case arises when the resource indicated by a locator proves to be another linking element. When an application traverses or displays such a link, it may be desired to read and traverse that link to whatever its resource(s) is (are) and operate on the result of that traversal. This has the benefit of allowing greatly increased indirection and flexibility; on the other hand, it might lead to potentially unbounded delays in traversing simple-looking links. This specification does not constrain the behavior of applications in this situation.

5.1 HREFs and Reference Types

Each locator is required to address a resource using an HREF (HREF may have at one point stood for "Hypertext reference"; the name is adopted for compatibility with existing practice). An HREF is a character string containing the information used to address the resource. An HREF may operate as a locator, as with a URL, a name, as with a URN or SGML FPI, or a query.

An HREF may be accompanied by a Reference Type, a name which identifies the interpretation of the HREF.

The HREF and reference type are provided, respectively, in the HREF and HRTYPE attributes.

5.2 Location Source

Many addressing mechanisms assume the existence of some sort of a base address whose value effects the interpretation of the address. To formalize this, every HREF has a location source, an object or objects which serves as the base address. In most cases the location source can be omitted and is implied to be the document element of the document that contains the link. However, this implied location source can also be specified as being the non-link element that refers to the link element (the referrer).

The location source is specified using the the location-source attribute. The format of the location-source string is not specified; to be useful, clearly it must be in a form that can be processed by the processor that can deal with the HREF and reference type to which it is attached. If the location-source attribute is omitted, the location source is implied according to the rule indicated by the IMPLIED-LOCSRC attribute.

The implied-locsrc attribute takes one of the values REFERRER or DOCELEM. The value REFERRER indicates that the implied location source is the referrer element. The value DOCELEM indicates that the location source is the document element, the document's root element.

The default value for implied-locsrc is DOCELEM.

5.3 SGML Reference Types

SGML HREFs use standard SGML Element and Entity addressing mechanisms. If the reference type is ENTITY, then the HREF must be an entity name which references an external entity. If the reference type is ELEMENT, then the HREF must be the value of a unique identifier attribute within the current document. If the reference type is SGML, then the HREF must contain an entity name interpreted as with ENTITY, followed by the character "#", followed by the value of a unique identifier attribute within the document referenced by the leading entity name.

5.4 URL Reference Types

If the reference type is URL, then the HREF must be a URL.

URLs may be used to refer to data objects of any kind.

5.5 TEI Locator Reference Types

If the reference type is TEI, the HREF must be a TEI locator.

XML uses a subset of the syntax defined for TEI extended pointers. These operate on groves as defined in DSSSL, using the grove plan (set of structural information) specified in HyTime. Every construct in such locators has a corresponding expression in DSSSL's SDQL query language, and most also have direct equivalents in the HyTime location module. A full description of the syntax is available in the TEI Guidelines; a summary appears as Appendix A of this document.

The basic form of such a locator is a series of location terms, each of which specifies a location, either absolute or (more frequently) relative to the prior one. Each term has a name, such as ID, CHILD, ANCESTOR, and so on, and can be qualified by parameters such as an instance number, element types, or attributes. For example, the locator string "CHILD (2 CHAP) (4 SEC) (3)" refers to the 3rd child of the 4th SEC within the 2nd CHAP within the referenced document.

Such a locator can be considered a query, and the extended pointer syntax a query language. Thus it can be appended to a URL that identifies an appropriate document, in order to locate some portion of that document; or can be declared as a HyTime query, and thus used in a fully HyTime-conforming manner. [need to add an example of the necessary declarations, similar to Eliot's straw proposal].

XML omits some features of TEI extended pointers:

  1. regular expression matching is not included, either as the "pattern" location term, or within parameters for other location terms.
  2. links to spans which are not elements are not supported, and so the "ditto" location term is not allowed.
  3. the "ref" location term for canonical references are not allowed.
  4. the "str" location term is not allowed, because of the subtleties associated with counting bytes and/or characters in international settings.
  5. the "HyQ" location term is not allowed, since it is obsolete.

[We may want to include a proposed TEI addition that provides for pointing directly to the values of attributes per se]

5.6 Query Reference Types

[Add a way to specify additional query languages]

6. Extended Link Groups

6.1 Identifying Extended Link groups

XML describes the syntax of link elements embedded in documents. Many applications, when processing a document, may wish to process not only the links embedded in that document, but links in other documents which point into it. For example, it may be desirable to highlight the resources of such links to make the linkage network's existence apparent. In other words, it may be appropriate to process, rather than a single document, a group of interlinked documents.

In these cases, the Extended Link Group (XLG) element may be used to store a list of identifiers of other documents that together constitute an interlinked document group. Each such document, which must be known as an external text entitiy, is identified using the DOC attribute of an Extended Link Document (XLD) element, which is a child element of the XLG.

XLG and XLD elements, just as with XLINK, LINK, or LOCATOR elements, may be recogized by the use of the XML-LINK attribute with the values XLG or XLD.

Here is the declaration for the XML form of the XLG and XLD elements:

<!ELEMENT XML-XLG (XML-XLD*)>
<!ELEMENT XML-XLD EMPTY>
<!ATTLIST XML-XLG 
          XML-LINK CDATA  #FIXED "XLG"
>
<!ATTLIST XML-XLD 
          XML-LINK CDATA  #FIXED "XLD"
          DOC      ENTITY #REQUIRED
>

6.2 LINKS and LINKSET Elements

Extended links may only occur in restricted contexts, in order to facilitate software finding them (their related resources, of course, may be anywhere at all).

First, extended links may occur in the LINKS element of a document, which is part of its header. So long as any part of the document remains open, all resources of all extended links in the header shall be known to the software and available to the user. Applications may apply their own conventions for when a document is no longer considered "open", except that any document any part of which remains in view, is open by definition.

Second, extended links may occur in separate documents that contain only extended links, called LINKSETS. Any document may specify any number of other documents and/or LINKSETS that should be opened. All resources specified in a LINKSET shall remain active at least as long as any of documents that points to that linkset remains open. [There is an argument to be made for keeping them open longer, such as for a whole session, or while any documents that have resources in the linkset are open; or for letting the referencing document(s) state how long they want it open; etc]. Software shall also provide a way for users to specify global or other LINKSETS, which should be kept open more persistently, such as throughout an entire user session, or automatically for all user sessions.


Appendices

A. The TEI extended pointer syntax

A.1.1.1 Location Ladders

Each location pointer specification consists of a sequence of location term s, each of which consists of a keyword specifying a location type followed by one or more parenthesized parameter lists, each of which specifies a location value via a list of parameters. Location types and values, and the parameters within a location value, must be separated by white space characters.

Using terms borrowed from HyTime , we say that each TEI location term in a specification provides the location source for the next, and the entire specification is equivalent to a location ladder . 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.

In formal terms:

ladder   ::=  locterm          |    ladder locterm 

A.1.1.2 Location Terms

The keywords used in location terms are these; references to the tree mean the tree representing the SGML document hierarchy.

root
points at the root of the target document
here
points at the location of the pointer
id
points at an ID within the target document
ref
gives a canonical reference to a location in the target document
child
indicates an element found by descending one level in the tree
descendant
indicates an element found by descending one or more levels in the tree
ancestor
indicates an element found by ascending one or more levels in the tree
previous
indicates an element found by traversing the older siblings of the current location source
next
indicates an element found by traversing the younger siblings of the current location source
preceding
indicates an element found by traversing the entire portion of the document preceding the current location source
following
indicates an element found by traversing the entire portion of the document which follows the current location source
pattern
specifies a regular expression to be located within the existing location source
token
points at one or more tokens in the character content of the location source
str
points at one or more characters in the character content of the location source
space
points at a location using coordinates in some (application-defined) n-dimensional space
foreign
points at a location using some non-SGML method, and gives the name of the method

In formal terms:

   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. 

The keywords are not case sensitive.

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 here or id is specified as the first location term, the beginning location source is always root . An empty location sequence thus is the same as root and specifies the entire destination entity.

Some of the location terms make sense only in documents that have tree-like representations; these are id , child , ancestor , descendant , previous , next , preceding , and following . 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 front end (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 child and descendant have no meaning, since character data has no descendants in the document tree; the first ancestor of such a location source is the element immediately containing the character data in question, and the siblings referred to by next and previous are the other children of that immediately containing element.

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.

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 fail . If any location term fails, the entire pointer fails. No backtracking or retrying is performed.

A.1.1.3 The ROOT Keyword

The location term root selects the document element. Since root is assumed as the implicit first term in any ladder, the following two location ladders have the same meaning:

   ROOT DESCENDANT (2 DIV1) DESCENDANT (2 DIV1) 

A.1.1.4 The HERE Keyword

The keyword here designates the location at which the pointer element itself is situated; it allows extended pointers to select items like the paragraph immediately preceding the one within which this pointer occurs . Since it ignores any existing location source, this keyword typically makes sense only as the first location term in a location specification.

To designate the paragraph preceding the current one , the following location ladder could be used:

HERE ANCESTOR (1 P) PREVIOUS (1 P)

(See below for descriptions of the keywords ancestor and previous .)

A.1.1.5 The ID Keyword

The resulting location is the element within the destination entity whose ID attribute has the value specified as the location value.

For example, the location specification

ID (a27)

chooses the necessarily unique element of the destination entity which has an attribute of declared value of type ID, whose value is a27 .

A.1.1.6 The CHILD Keyword

The child location type specifies an element or span of character data in the document hierarchy using a location value which functions as a domain-style 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:

  1. an instance indicator, which is a signed or unsigned integer or the special value ALL
  2. optionally, an SGML generic identifier
  3. optionally, one or more pairs, the first matching an SGML attribute name and the second matching an SGML attribute value

In formal terms, the location value of child is a series of steps :

steps    ::=  '(' step ')'          |    steps '(' step ')'  step     ::=
instance          |    instance element          |    instance element avspecs
avspecs  ::=  attribute value          |    avspecs attribute value  

Location values of the same form are also used by the keywords descendant , ancestor , previous , and next.

If an instance indicator alone is specified, as a number n , it selects the n th child of the location source. If the special value ALL is given, then all the children of the location source are selected. If the instance indicator is specified with following parameters, it selects all, or the n th, among those children of the location source which satisfy the other parameters. Negative numbers count from the last child of the location source to the first. The location source must contain at least n children; if it does not, the child term fails.

In formal terms, the first parameter of a step is an instance indicator, which in turn is either the special value ALL or a signed integer:

instance ::=  'ALL'          |    signed  signed   ::=  NUMBER
// default sign is +          |    '+' NUMBER          |    '-' NUMBER  

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

CHILD (3 DIV1) (4 DIV2) (29 P)

chooses the 29th paragraph of the fourth sub-division of the third major division of the initial location source.

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 the second section , the third paragraph , 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.

The generic identifier may be specified as a normal SGML name or using the reserved values #CDATA or * . If the generic identifier is specified as * , any generic identifier is matched; this means that CHILD (2 *) is synonymous with CHILD (2) . If the second parameter is #CDATA , the location term selects only untagged sub-portions of an element having SGML mixed content.

The location ladder

CHILD (3 #CDATA)

thus chooses the third span of character data directly contained by the current location source. If the location source is a paragraph containing

  1. a sentence (A)
  2. an embedded quotation, marked as a q
  3. another sentence (B)
  4. an embedded note, marked as a note
  5. another sentence (C)
  6. a second embedded quotation, marked as a q
where the three sentences A, B, and C are character data enclosed by no element smaller than the paragraph itself, then CHILD (3 #CDATA) selects sentence C, while CHILD (3) selects sentence B.

If specified as a name, 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).

In formal terms the second parameter of a step is defined thus:

element  ::=  NAME          |    '#CDATA'          |    '*'          |
'(' regular ')' 

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.

The third, fifth, seventh, etc., parameters are interpreted, if specified, as attribute names. Like generic identifiers, attribute names may be specified as * in location ladders in the (unlikely) event that an attribute value constitutes a constraint regardless of what attribute name it is a value for.

For example, the location term

CHILD (1 * TARGET *)

selects the first child of the location source for which the attribute target has a value.

As with generic identifiers, attribute names are case sensitive if and only if the SGML declaration says they are.

In formal terms, the attribute-name parameter of a tree-traversal step is defined thus:

attribute ::= NAME          |    '*'    

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 using the two special values #IMPLIED and * .

For example, the location specification

CHILD (1 * N 2) (1 * N 1)

chooses an element using the global n attribute. Beginning at the location source, the first child (whatever kind of element it is) with an n attribute having the value 2 is chosen; then that element's first direct sub-element having the value 1 for the same attribute is chosen.

If specified with quotation marks or as a regular expression, the attribute-value parameter is case-sensitive; otherwise not.

The location specification

CHILD (1 FS RESP #IMPLIED)

selects the first child of the location source which is an fs element for which the resp attribute has been left unspecified.

In formal terms, the attribute-value parameter of a tree-traversal step is defined thus:

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. 

A.1.1.7 The DESCENDANT Keyword

If the descendant keyword is used, the location term selects an element or character-data string which is a descendant of the current location source. The parameters are the same as for child. 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.

The location specification

ID (a23) DESCENDANT (2 TERM LANG DE)

thus selects the second term element with a lang of de occurring within the element with an id of a23 . 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.

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

DESCENDANT (-1 NOTE)

thus chooses the last note element in the document, that is, the one with the rightmost start-tag.

A.1.1.8 The ANCESTOR Keyword

The ancestor 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 child. However, the ancestor keyword selects elements from the list of containing elements or ancestors 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).

For example, the location term

ANCESTOR (1 * N 1) (1 DIV)

first chooses the smallest element properly containing the location source and having attribute n with value 1 ; and then the smallest div element properly containing it.

A.1.1.9 The PREVIOUS Keyword

The previous 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 parent element as siblings ; those which precede a given element or string in the document are its elder siblings ; those which follow it are its younger siblings .

The instance number in the location value of a previous term designates the nth elder sibling of the location source, counting from most recent to less recent. The location ladder

ID (a23) PREVIOUS (1)

thus designates the element immediately preceding the element with an id of a23 . 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

PREVIOUS (-1)

designates its eldest sibling and is thus synonymous with the ladder

ANCESTOR (1) CHILD (1)

The value ALL may be used to select the entire range of elder siblings of an element: the location ladder

ID (a23) PREVIOUS (ALL)

thus designates the set of elements which precede the element with an id of a23 and are contained by the same parent.

A.1.1.10 The NEXT Keyword

The keyword next behaves like previous , but selects from the younger siblings of the location source, not the elder siblings. The location ladder

ID (a23) NEXT (1)

thus designates the element or string immediately following the element which has an id of a23 . 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

NEXT (-1)

designates its youngest sibling and is thus synonymous with the ladder

ANCESTOR (1) CHILD (-1)

A.1.1.11 The PRECEDING Keyword

The preceding 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 PRECEDING and FOLLOWING , elements are interpreted as occurring where their start-tag occurs.) The PRECEDING keyword thus resembles PREVIOUS but differs in searching a larger set of strings and elements; its result is not guaranteed to be a subset of its location source.

The instance number in the location value of a preceding term designates the nth element or character-data string preceding the location source, counting from most recent to less recent. The location ladder

ID (a23) PRECEDING (5)

thus designates the fifth element or string before the element with an id of a23 . Negative instance numbers also designate preceding elements or strings, counting from the eldest to the youngest; the ladder The location source must have at least as many elder siblings as the absolute value of the instance number; otherwise, the preceding term fails. The value ALL may be used to select the entire portion of the document preceding the beginning of the location source.

A.1.1.12 The FOLLOWING Keyword

The keyword following behaves like preceding , but selects from the portion of the document following the location source, not that preceding it.

A.1.1.13 The TOKEN Keyword

The token keyword selects a sequence of one or more tokens chosen from within the character content of the location source, where tokens are counted exactly as for the corresponding HyTime dataloc form with quantum=word. 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.

This location type must not be used to count across element boundaries.

For example, the location specification

ID (a27) TOKEN (3 5)

chooses the 3rd, 4th, and 5th tokens from the content of the element whose identifier is a27 . If this element contained the string This is _not_ a very good idea , the target selected would be not_ a very .

In formal terms the location value of the token and str keywords is defined as a range:

range    ::=  NUMBER          |    NUMBER NUMBER 

A.1.1.14 The SPACE Keyword

The space 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.

The location value for space 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).

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.

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).

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.

For example,

SPACE (2D) (0 0) (1 1)

specifies the location of the unit square tangent to the origin in quadrant 1 of a common graph.

The location value for a space location term is a NAME enclosed in parentheses, followed by a point pair:

pointpair ::= '(' numbers ')'          |    '(' numbers ')' '(' numbers
')'  numbers  ::=  signed          |    numbers signed 

A.1.1.15 The FOREIGN Keyword

The foreign 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.

The meaning of the foreign 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 foreign location types must be specified in the TEI header, as a series of paragraphs at the end of the encodingDesc element defined in section * . If more than one such type is used, it is TEI recommended practice that the first parameter list to foreign be a name associated with the particular type by documentation in the TEI header.

For example, assume that some program uses a proprietary data format called XFORM, and that the program has supplied an identifier 06286208998 for some piece of data it owns. Then the location specification

FOREIGN (XFORM) (06286208998)

would be one way of expressing a link to that piece of data.

B. Production note

The HTML copy of this draft specification was generated automatically from an XML source file using a custom formatter written in perl.

C. W3C SGML Working Group and Editorial Review Board

C.1 W3C SGML Working Group

C.2 W3C SGML Editorial Review Board