Targeting text strings

One of the most significant features of the XPointer language is its ability to target a specific character, word, phrase or sentence of interest, without having to rely upon the presence of an identifying element. For example, the name 'Scarborough' may be of interest in the following text, but the enclosing Paragraph element also contains other text:

<Para>Are you going to Scarborough fair?</Para>

However, the name 'Scarborough' does have an exact location in the document relative to other occurrences and surrounding element structures. But it is not necessary to know and specify the position of the string (in the way that it is necessary to know the identifier or exact location of an element). Instead, an XPointer-based system is able to find the string for itself.

String-range function

Designating a string of text as a link resource is accomplished using the string-range() function:

xpointer(string-range(...))

The first parameter is the node set to search through, and the second is the text string to be found. In the following example, the second chapter of the book is searched for paragraphs that contain the string 'find me':

xpointer(string-range(//chapter[2]/para, "find me"))

   <book>
     <chapter>...</chapter>
     <chapter>
       <para>You will find me here.</para>
       <para>You will also find me here.</para>
     </chapter>
   </book>

Ignored markup

Element tags and other markup tags are all ignored when matching strings. The example above would work equally well in the following circumstance:

<para>You will find <emph>me</emph> here.</para>

<para>You will also <emph>find</emph> me here.</para>

As already stated, this means that the selection can span parent structures too:

string-range(//, "here to here")
   <para>Select the text from <emph>here</emph></para>
   <para> to <emph>here</emph>. But not this.</para>

Occurrence identifier

A specific instance of the string can be isolated using normal XPath predicate filters. The following example selects the second occurrence of the string 'find me' within the second chapter of the book:

string-range(/book/chapter[2], "find me")[2]
					

As stated above, any embedded markup is ignored, so it does not matter if the second occurrence of 'find me' is actually inside an embedded element. In the following example, the second occurrence of the string is found in every chapter:

string-range(/book/chapter, "find me")[2]

   <chapter>...find me find me...</chapter>
   <chapter>...find me <emph>find me</emph>...</chapter>

Finally, in this example the second occurrence of the string in every text node, comment and processing instruction is targeted:

string-range(/, "find me")[2]

Partial string selection

Sometimes, the string to be found is not quite the same as the string to be highlighted, but also contains an essential context for this string. For example, it may be desirable to point to the name 'Scarborough', but only when it occurs within the string 'going to Scarborough fair'.

Two further parameters can be added to the string-range() function to select just part of the given string. The first parameter is a starting position number, which must not be zero. The value '1' indicates a position just prior to the first character in the string (this being the default value). The value '10' indicates a position just before the tenth character (character ten is to be included in the selection):

string-range(//para, "going to Scarborough fair", 10)

The next parameter value is the number of characters to select from this starting position. By default, all characters up to the end of the string are selected, as indicated above. A value of '0' indicates no characters, and a point rather than a range is specified. In the following example, only the name 'Scarborough' is selected:

string-range(//para, "going to Scarborough fair", 10,
						11)

Finally, it is even possible to select additional characters:

string-range(//para, "find me", 1, 12)

Non-normalized whitespace

Multiple whitespace characters are not normalized to a single space when matching strings. A search for 'find me' would not find the string 'find me'.