XPointers in Links (XML in a Nutshell, 2nd Edition)

11.2. XPointers in Links

Obviously, what an XPointer points to depends on to which document it's applied. This document is specified by the URL to which the XPointer is attached. For example, if you wanted a URL that pointed to the first name element in the document at http://www.cafeconleche.org/people.xml, you would type:

http://www.cafeconleche.org/people.xml#xpointer(//name[position( )=1])

If the XPointer uses any characters that are not allowed in URIs--for instance, the less than sign <, the double quotation mark ", or non-ASCII letters like é--then these must be hexadecimally escaped as specified by the URI specification before the XPointer is attached to the URI. That is, each such character is replaced by a percent sign followed by the hexadecimal value of each byte in the character in the UTF-8 encoding of Unicode. Thus, < would be written as %3C, " would be written as %22, and é would be written as %C3%A9.

In HTML, the URLs used in a elements can contain an XPointer fragment identifier. For example:

<a href = "http://www.cafeconleche.org/people.xml#xpointer(//name[1])">
  The name of a person
</a>

If a browser followed this link, it would likely load the entire document at http://www.cafeconleche.org/people.xml and then scroll the window to the beginning of the first name element in the document. However, no browsers yet support XPointer, so the exact behavior is open for debate. In some situations it might make sense for the browser to show only the specific element node(s) the XPointer referred to rather than the entire document.

Since XPath can only locate nodes in a well-formed XML document, XPointers can only point into XML documents. You can't use them to link into nonwell-formed HTML, plain-text files, or other non-XML documents. However, linking from HTML documents is perfectly fine, as is printing XPointers in books, painting them on the sides of buildings, or communicating them by any means by which text can be communicated.

XPointers are more frequently used in XLinks. For example, this simple link points to the first book child of the bookcoll child of the testament root element in the document at the relative URL ot.xml:

<In_the_beginning xlink:type="simple"
   xlink:href="ot.xml#xpointer(/testament/bookcoll/book[position( )=1])">
  Genesis
</In_the_beginning>

In extended links, an XPointer can help identify both the starting and ending resources of an arc. For example, this extended XLink establishes an arc between the last v element in the document at the relative URL ot.xml and the first v element of the document at the relative URL nt.xml. Then it establishes a link from the first v element of nt.xml to the last v element of ot.xml:

<Bible xlink:type="extended" xmlns:xlink="http://www.w3.org/1999/xlink">

  <testament xlink:type="locator" xlink:label="ot"
             xlink:href="ot.xml#xpointer(//v[position()=last( )])"/>
  <testament xlink:type="locator" xlink:label="nt"
             xlink:href="nt.xml#xpointer(//v[position( )=1])" />

  <next     xlink:from="ot" xlink:to="nt"/>
  <previous xlink:from="nt" xlink:to="ot"/>

</Bible>

Links can even be purely internal; that is, they can link from one place in the document to another place in the same document. The slide element shown in this example contains simple XLinks that point to the first and last slide elements in the document:

<slide xmlns:xlink="http://www.w3.org/1999/xlink">

  <point>Acme Wonder Goo is a delicious dessert topping!</point>
  <point>Acme Wonder Goo is a powerful floor cleaner!</point>
  <point>It's two products in one!</point>

  <first xlink:type="simple"
         xlink:href="#xpointer(//slide[position( )=1])">
    Start
  </first>
  <last  xlink:type="simple"
         xlink:href="#xpointer(//slide[position()=last( )]))">
    End
  </last>
</slide>

When the XPath expressions used in an XPointer are themselves relative, the context node is the root node of the entity that contains the XPointer.