The following contexts require various types of escaping to be applied to XPointers.

The XPointer-processor handles undoing A. All other escaping is undone (in reverse order of application) outside the processor. If the result passed to the processor does not conform to the syntactic rules for XPointers in this specification, a syntax error results.

The set of characters for XPointers is necessarily the same as for XML, namely . However, some Unicode characters are disallowed from URI references. Thus, the disallowed characters in XPointer-containing URI references must ultimately be encoded and escaped in order for URI resolver software to be able to handle them.

The disallowed characters include all non-ASCII characters, plus the excluded characters listed in Section 2.4 of , except for the number sign (#) and percent sign (%) and the square bracket characters re-allowed in . Disallowed characters are escaped as follows:

The following table shows the progressive escaping of an XPointer containing circumflexes, double quotation marks, and spaces so that it can appear in an XML document.

The following table shows the progressive escaping of an XPointer containing accented characters. The XPointer is intended to appear in an XML document encoded in US-ASCII, which does not allow the letter é to appear directly.

The full form of addressing consists of one or more XPointer parts; each starts with a scheme name and is followed by a parenthesized expression, and multiple parts are optionally separated by white space. When the scheme is xpointer (see for more information), the associated expression provides access to nodes and non-node locations in an XML document's or external parsed entity's data set.

A bare name stands for the same name provided as the argument of id(). For example, the first XPointer below is the bare-name equivalent of the second, which uses the full XPointer form:

The bare-name shorthand is provided for two reasons:

A child sequence locates an element by stepwise navigation using a sequence of integers separated by slashes (/). Each integer n locates the nth child element of the previously located element, equivalent to an XPath location step of the form *[n]. If the resource passed to the Xpointer-processor is a document, the first integer in the sequence will be 1, and it locates the document element; if the resource is an external parsed entity, the first integer locates one of the top-level elements.

A child sequence can optionally begin with a name before the integers; the name locates an element as described for bare names in . For example, the following two XPointers would locate the same XML information, assuming intro is the ID attribute value of the element that is the fifth child of the second child of the document element:

For any XPointer part that uses the xpointer scheme, the evaluation context of that part must be initialized to a set of namespace declarations consisting of a declaration of the xml prefix, bound to the URI http:/www.w3.org/XML/1998/namespace, plus any namespace declarations specified by xmlns XPointer parts appearing to its left. Each xmlns part defines a namespace declaration as a prefix (NCName) and namespace URI (XPtrNsURI). In the event that two or more xmlns parts specify the same prefix, the rightmost one is used. Any xmlns parts attempting to override the xml prefix must be ignored.

As an example, assume the following target XML resource:

Evaluation of the following XPointer will fail; it cannot be known which a element is desired because no namespace declarations are in scope:

The following avoids this evaluation failure and ensures that the outer a element is addressed:

The following (printed on two lines for convenience) allows for accurate addressing of the inner a element; note that the prefix used inside the XPointer need not correspond to the prefix (if any) actually used in the target resource:

A location of type point is defined by a node, called the container node, and a non-negative integer, called the index. It can represent the location preceding or following any individual character, or preceding or following any node in the data set constructed from an XML document or external parsed entity. Two points are identical if they have the same container node and index.

When the container node of a point is of a node type that can have child nodes (that is, when the container node is an element node or a root node), then the index is an index into the child nodes; such a point is called a node-point. The index of a node-point must be greater than or equal to zero and less than or equal to the number of child nodes of the container. An index of zero indicates the point before any child nodes, and a non-zero index n indicates the point immediately after the nth child node.

When the container node of a point is of a node type that cannot have child nodes (i.e., text nodes, comments, processing instructions, attribute nodes, and namespace nodes), then the index is an index into the characters of the string-value of the node; such a point is called a character-point. The index of a character-point must be greater than or equal to zero and less than or equal to the length of the string-value of the node. An index of zero indicates a point immediately before the first character of the string-value, and a non-zero index n indicates the point immediately after the nth character of the string-value.

A point location does not have an expanded-name.

The string-value of a point location is empty.

The axes of a point location are defined as follows:

A location of type range is defined by two points, a start point and an end point. A range represents all of the XML structure and content between the start point and end point. This is distinct from any list of nodes and/or characters, in part because some nodes might be only partly included. The start point and end point of a range must be in the same document or external parsed entity. The start point must not appear after the end point in document order (see ).

A range whose start point and end point are equal is a collapsed range.

If the container node of one point of a range is a node of a type other than element, text, or root, the container node of the other point of the range must be the same node. For example, it is allowed to specify a range from the start of a processing instruction to the end of an element, but not to specify a range from text inside a processing instruction to text outside it.

A range location does not have an expanded-name.

The string-value of a range location consists of the characters that are in text nodes and that are between the start point and end point of the range.

The axes of a range location are identical to the axes of its start point. For example, the parent axis of a range contains the parent of the start point of the range.

A covering range is a range that wholly encompasses a location. For every location, a covering range is defined as follows:

XPointer extends the XPath production for NodeType... by adding items for the point and range location types. The production (number 38 in XPath) becomes as follows:

This definition allows NodeTests to select locations of type point and range from a location-set that might include locations of many types.

XPointer extends XPath's concept of document order to cover point and range locations. The concept applies equally in external parsed entities.

A point can be either a node point or a character point. Conceptually, node points label gaps between nodes, while character points occur within a node, between the node points to the right and left of the node.

Thus, an element P has a node point before and after it. If the P element contains sub-elements and/or text nodes, there are node points for the gap before the first child node, between each successive pair of child nodes, and after the last child node; they are numbered in order from 0.

WIthin any text node, there are character points preceding the first character of the text, between each successive pair of characters, as well as after the last character; they are numbered in order from 0.

For any point, there is an immediately preceding node defined as follows (except that there is no point defined preceding or following the root):

The following diagram illustrates the relation between container nodes, node-points and character-points.

For each location in the context, range-to returns a range. The start point of the range is the start point of the context location (as determined by the start-point function), and the end point of the range is the end point (as determined by the end-point function) of the location found by evaluating the expression argument with respect to that context location.

The change made to the XPath syntax to support the range-to construct corresponds to a single addition to the Step production of the specification. The original production is as follows:

The XPointer version is as follows:

This change is a single exception for the range-to function. It is not a generic change and is not extensible to other functions. The modified production expresses that a range computation must be made for each of the locations in the current location list.

As an example of using the range-to function, the following XPointer locates the range from the start point of the element with ID chap1 to the end point of the element with ID chap2.

As another example, imagine a document that uses empty elements (such as <REVST/> for revision start and <REVEND/> for revision end) to mark the boundaries of edits. The following XPointer would select, for each revision, a range starting at the beginning of the REVST element and ending at the end of the next REVEND element:

For each location in the location-set argument, string-range returns a set of ranges determined by searching the string-value of the location for substrings that match the string argument. An empty string is defined to match before each character of the string-value and after the final character.White space in a string is matched literally, with no normalization except that provided by XML for line ends and attribute values. Each non-overlapping match can contribute a range to the resulting location set.

The third argument gives the position of the first character to be in the resulting range, relative to the start of the match. The default value is 1, which makes the range start immediately before the first character of the matched string. The fourth argument gives the number of characters in the range; the default is that the range extends to the end of the matched string. Thus, both the start point and end point of each range returned by the string-range function will be character points.

Element boundaries, as well as entire embedded nodes such as processing instructions and comments, are ignored as specified by the definition of string-value in .

For any particular match, if the string argument is not found in the string-value of the location, or if the third and fourth argument indicates a range that is wholly beyond the beginning or end of the document or entity, then no range is added to the result for that match.

The start and end points of the range-locations in the returned location-set will all be character points.

For example, the following expression returns a range that selects the 17th occurrence of the string Thomas Pynchon occurring in a title element:

As another example, the following expression returns a collapsed range whose points immediately precede the letter P (8 from the start of the string) in the third occurrence of the string Thomas Pynchon in a P element:

Alternatively this could be specified as follows:

String-values are views into only the string content of a document or entity; they do not retain the structural context of any non-text nodes interspersed with the text. Because the string-range function operates on a string-value, markup that intervenes in the middle of a string does not prevent a match. (Note that for this reason, a string-range match is a range describing the relevant substring of the string-value, not necessarily a contiguous string in a single text node in the document.) For example, if the 17th occurrence of Thomas Pynchon had some inline markup in it as follows, it would not change the string returned by the XPointer application:

The following expression selects the fifth exclamation mark in any text node in the document and the character immediately following it:

Although these examples locate ranges via text in the string-values of elements, string-range is useful for locating ranges that are wholly enclosed in other node types as well, such as attributes, processing instructions, and comments.

The following functions are related to ranges.

The here function is meaningful only when the XPointer being interpreted occurs in an XML document or external parsed entity; otherwise the XPointer part in which the here function appears fails. When in an XML context, the here function returns a location-set with a single member. There are two possibilities for the location returned:

In the following example, the here function appears inside an XPointer that is in an attribute node. The XPointer as a whole, then, returns the slide element just preceding the slide element that most directly contains the attribute node in question.

The origin() function is meaningful only when the XPointer is being processed in response to traversal of a link expressed in an XML document. The origin function enables addressing relative to third-party and inbound links such as defined in XLink. This allows XPointers to express relative locations when links do not reside directly at one of their endpoints. The function returns a location-set with a single member, which locates the element from which a user or program initiated traversal of the link. (See for information about traversal.)

It is a resource error to use origin in the fragment identifier portion of a URI reference where a URI is also provided and identifies a resource different from the resource from which traversal was initiated, or in a situation where traversal is not occurring.