Unlike some of the rest of the terms in this section, “resource” is not defined directly. Instead, under its definition of subresources, the previous version of the XPointer spec said, “...the whole resource being referred to is an XML document or external parsed entity.”^[1] That is, a resource is the entity within which some specific content resides.

Note that XPointer uses “resource” rather differently than the way it’s used in “Uniform Resource Identifier” — the familiar URI of the Web. The authoritative reference for URIs is IETF RFC 2396 (“Uniform Resource Identifiers (URI): Generic Syntax,” located at http://www.ietf.org/rfc/rfc2396.txt), which defines the term in this way (emphasis added):

Thus, in a URI such as http://www.example.org/index.html, the resource is not the document so pointed to but the address that points to it. In practice, XPointer works differently: if a given XPointer is to work at all, it must be applied to a portion of a particular XML document, not just to the address of whatever document happens to be there at the time. (On the other hand, one might be excused for wishing that a resource would always be a resource, regardless of the context in which she encounters the term.)

A subresource is the specific fragment of content identified by the XPointer. This may, but will almost never, be an entire document; it’s far more likely, because XPointer uses XPath, that the subresource in question will be a single element, or an attribute, or some other (perhaps more complex) node-set. (As you’ll see in a moment, however, XPointer expands on XPath’s notion of node-sets, in the form of location-sets.)

If the subresource is the what — the content — identified by an XPointer, the location is the where.

(I wouldn’t be surprised to see the terms subresource and location being used interchangeably, although this would make purists crazy. If I’m standing at a stove preparing a meal and ask you to “hand me that can,” I of course hope you will not empty the can first — that you will deliver it to me contents and all. In the same way, people exchanging URIs often say that someone “sent me a web page”... even though, if anything, they are being sent to the page rather than the other way around.)

The spec makes an analogy between the term “node” as used in XPath and the term “location” as used in XPointer. Why then do we need a new term? Because XPointer can handle (via XPath) not only nodes, but two other forms of addressing: points and ranges. Both of these terms are discussed in the sections that follow.

As an XPointer location is to an XPath node, an XPointer location-set is to an XPath node-set. That is, a location-set is the complete list of locations identified by an XPointer. (And as in the XPath counterparts, if an XPointer has only a single location, it might just as well be considered a location-set containing only a single member.)

Note that the addition of the point and range location types requires enhancing the concept of document order established by XPath. This subject is addressed further in Chapter 9.

A point in XPointer terms is the abstract location between two adjacent chunks of text content. Figure 7-1 illustrates.

Figure 7-1. Point-type locations

Ignoring the newline characters and other whitespace added for legibility, Figure 7-1 highlights the following point-type locations (among many others present in the document):

Point-type locations also exist at the interstices between the element boundaries. For instance, although not highlighted in Figure 7-1, there’s a point-type location following the close of the gerund element. Just as important, though, are the places where there are no point-type locations at all. For instance, there is no point-type location between any adjacent characters in the name of an element in the element’s start tag.

An XPointer range is the entire block of text content bounded by two points. In Figure 7-1, each individual word in the document exists in a range between the points immediately following and preceding the containing element’s start and end tags, respectively. Each individual character also exists in its own range (the points in question immediately precede and follow the character). Note that a point alone doesn’t “contain” anything; it must be paired in a range with another point first.

There’s no particular requirement that a range be limited to a single containing element. For instance, you could establish a range by fixing one point before the p in prime and another point after the n in senility. The resulting range (again, ignoring whitespace) would be primeofmysen.

One interesting aspect of these two XPointer location types, as opposed to the node types available under XPath, is that points and ranges more closely reflect a document’s physical characteristics, not its logical or structural ones. There’s no hierarchical containment going on in a range (except in the limited sense of “text contained within two points”).

This difference is reflected in the common applications to which ranges and points might be put to use. In particular, they’re useful as a way of formally expressing the physical act of selecting text, such as with a mouse or with keyboard commands. XPath nodes, on the other hand — while they of course are defined by a given document’s physical characteristics, sequences of characters, and such — are purely logical constructs with no physical user-interface counterparts.

On the other hand, because points can’t be located within certain portions of the markup (such as in element names), a range can’t span just any text physically present in the document — as if you had the source code open in a text editor. What you can select is still constrained by certain features of the logical node tree.

You’ll learn much more about points and ranges in the rest of this chapter and the two that follow, especially Chapter 9.

Syntax errors are to an XPointer processor what well-formedness errors are to an XML processor — or, indeed, what syntax errors are to the compiler of a traditional programming language: they violate the rules of the language itself. In XPointer as in other languages meant for machine processing, when the standard says “A given left parenthesis must be balanced by a right parenthesis and vice versa,” it means just that. You can’t “balance” a left parenthesis with a square bracket, an asterisk, or the digit 9. If an XPointer fails syntactically, it doesn’t make any difference if it falls into one of the other error classifications — the processor won’t even be able to figure it out. Thus, syntax errors might be considered the most “catastrophic” and unrecoverable sort of XPointer error.

Once an XPointer passes muster syntactically, it’s still not out of the woods as a “valid” XPointer. At this point, considering the XPointer as a simple string of characters — which is, after all, what a processor does when it verifies an XPointer’s syntax — gives way to determining its usefulness for XPointer’s stated purpose: locating some portion(s) of an XML-based document. When the document in question — the resource itself — doesn’t exist, the processor must report a resource error to the controlling application.

A subresource error, on the other hand, must be reported when a given XPointer identifies a specific subresource that doesn’t exist — even though the document itself does. For example, consider this document:

<villain>
   <name>Blofeld</name>
   <film>Thunderball</film>
</villain>

A syntactically correct XPointer (one passing the syntax-error check) could point, correctly, to this document itself (and therefore pass the resource-error check); but if the XPath expression built into the XPointer referred to some descendant of the root element named, say, evil_world_dominaton_plan, the processor would report a subresource error. That is, the resource as a whole exists but not the particular portion of the resource identified by the XPointer.

Note in particular that while an empty node-set is perfectly legitimate in pure XPath terms — XPath allows for such a thing — an empty node-set is an XPointer error, called a “failure” by the XPointer Framework.

A couple of characters have special significance to the XPointer standard itself. The first of these is the parenthesis, which in XPointer (as in other languages) is always expected to appear in left/right pairs. Under certain (and probably extremely rare) circumstances, you may need to use a parenthesis as a literal character in an XPointer, unbalanced by the opposite parenthesis. In this case, you escape the parenthesis by prefixing it with a circumflex character, ^. Thus, a literal left or right parenthesis would be legally represented by ^( or ^), respectively.

The second XPointer-significant character, therefore, is the circumflex itself. To escape a circumflex — that is, to cause the processor to recognize the character as a literal, not as an escaping character — prefix it with another circumflex. Thus, a literal circumflex can appear in an XPointer as ^^. All other uses of the circumflex character in an XPointer are illegal, resulting in a syntax error.

This is not to say, of course, that a literal circumflex may not be used elsewhere in an instance document. Remember that this constraint applies only to a circumflex within an XPointer.

It’s common for an Internet address — a URI — to include somewhere within it certain special characters such as spaces, percent signs, and so on. Web browsers and other Internet applications may or may not choke on these special characters. But if they follow the URI standard, they’re supposed to choke; this standard requires that such characters in a URI be escaped, using a percent sign and the Unicode value for the character.

For instance, consider the following URI:

http://my.dot.com/my documents/index.html

The space between my and documents is supposed to be escaped, using the hexadecimal Unicode value for the space character, so its correct form is:

http://my.dot.com/my%20documents/index.html

Like other standards built on the Internet’s basic linking infrastructure, XPointer follows the rules established for URIs — including, in this case, the rules for escaping special characters. These rules (as well as the others for URIs) are laid out in two IETF RFCs, numbers 2396 and 2372, which you can find at http://www.ietf.org/rfc/rfc2396.txt and http://www.ietf.org/rfc/rfc2732.txt, respectively.

Finally, of course, XPointer — being often used in XML documents — is no exception to the general rules of XML well-formedness. If your XPointer appears in an XML document and includes special XML-significant literal characters, such as greater-than signs or ampersands, you must escape them with standard XML entity references (such as > and &, respectively). Also remember that you must escape, with character entity references, any character(s) in the XPointer that can’t be expressed in your instance document’s own encoding; if you’re working in a U.S.-ASCII-encoded document, therefore, you have to escape additional characters in the ISO-8859 encoding. In this scenario, for example, you’d have to escape Á (capital A with an acute accent) as either Á (hexadecimal form) or Á (decimal form).

XPointer specifications often use syntax that cannot be used directly in a URL. To implement them, you must use a prodecure called progressive escaping. This term is defined nowhere in the spec; but from the context, it clearly refers to how you, an XPointer-using document author, might apply successive levels of the above escaping types to a XPointer.

To repeat, this progressive-escaping mechanism does not suggest that this stack of escaping sieves is to be implemented in an XPointer processor: it’s meant to make an XPointer acceptable to such a processor in the first place. On the processing side, each successive application layer — XML, the HTTP-aware application, and XPointer itself — unescapes the XPointer in reverse order, from the outside in as it were.

translate(., "(  )%&^", "[]@v")