== XPointers and XLink

=== XPointer ===
See [http://www.w3.org/TR/xptr-framework/ XML Pointer Language (XPointer)]. XPointer could be used in all URI attributes. 

Examples:

* <p>This is discussed in <div xlink:href="example.xml#xpointer((//p)[1])">the first paragraph of the example document</div>.</p>  
* <p>This is discussed in <div xlink:href="example.xml#xpointer(id('4711')/div[1])">the first division of the example document</div>.</p>
* <p>This is discussed in <div xlink:href="example.xml#element(/1/2)">the second element of the first element</div>.</p>
* <p>Einstein said in his diary that he doesn't like a further delay of his shipping tour to south america (see <note xlink:href="http://mpdl.mpiwg-berlin.mpg.de/physics/einstein/diary.xml#xpointer(id('page53')/echo[1]/text[1]/body[1]/chap[1]/p[1]/s[2])">page 53, sentence 2</note>).</p>

==== XPoints ====

  [[Image(xpoint.png)]]
  
* Examples
  * point(1.0) is just inside the beginning of the p element.
  * point(1.2) is between the end of the em element and the following text node (which contains "world.").
  * point(.0) immediately precedes the root node.
  * point(1/2/1.1) immediately following the "b" in the middle text node.

==== Range ====
* xpointer(id("chap1")/range-to(id("chap2"))) (the range from the start point of the element with ID "chap1" to the end point of the element with ID "chap2")
* string-range(//title,"Thomas Pynchon")[17] (the 17th of those "Thomas Pynchon" strings appearing in a title  element)
* <p>See the <note xlink:href="http://mpdl.mpiwg-berlin.mpg.de/physics/einstein/diary.xml#xpointer(id('page53')/echo[1]/text[1]/body[1]/chap[1]/p[1]/s[2]/range(1.3, 1.10))">text passage on page 53, sentence 2, character 3 to 10</note>).</p>

==== Support of XPointer ====

The MPDL project sets a special focus on the presentation of document pages. An important requirement for MPDL-XPointers is the support of pointers relative to document pages. Another special requirement is to point not only to elements on a page but also to text portions in elements (point or range). XPointer could be used in all Echo and TEI URI attributes. The MPDL project supports the following subset of XPointer (in the near future):

* XPointer to a page in an XML document. The result of the XPointer URL is the whole page. Example: 
  * <p>... (see <ref target="http://mpdl-proto.mpiwg-berlin.mpg.de/tei/en/ramones_2004.xml#xpointer(id('page6'))">Dick Porter: Ramones – The Complete Twisted History, London: Plexus, 2004. Page 6. ISBN 0859653269</ref>)
  * if the document contains no pages (no <pb/> elements) then the page number doesnt't have to be specified (all elements are on the first page internally)
  * Working example: 
    * [[http://mpdl-text.mpiwg-berlin.mpg.de/documents/echo/la/Benedetti_1585.xml#xpointer(id(%27page7%27))|Benedetti, page 7]]
* XPointer to an element on a page in an XML document. The result of the XPointer URL is the page and the requested element is highlighted. Example: 
  * <p>Joey Ramone said: "When we started up in March of ’74, it was because the bands we loved, the rock ’n’ roll that we knew, had disappeared. We were playing music for ourselves." (see <ref target="http://mpdl-proto.mpiwg-berlin.mpg.de/tei/en/ramones_2004.xml#xpointer(id('page6')/tei[1]/text[1]/body[1]/chap[1]/p[1]/s[2])">page 6, sentence 2</ref>).</p>
  * Working example: 
    * [[http://mpdl-text.mpiwg-berlin.mpg.de/documents/echo/la/Benedetti_1585.xml#xpointer(id(%27page7%27)/echo[1]/text[1]/div[1]/div[2]/p[1]/s[1])|Benedetti, page 7, sentence 1]]
* XPointer to a text portion (range) of an element on a page in an XML document. The result of the XPointer URL is the page and the requested text portion of the element is highlighted.
  * function "range" with two parameters: 
    * from: start point of the range as count of text characters from the beginning of all the text nodes of the element
    * to: end point of the range as count of text characters from the beginning of all the text nodes of the element
  * Example: 
    * <p>The Ramones started up in March 1974 (see <ref target="http://mpdl-proto.mpiwg-berlin.mpg.de/tei/en/ramones_2004.xml#xpointer(id('page6')/tei[1]/text[1]/body[1]/chap[1]/p[1]/s[1]/range(22, 34))">page 6, sentence 1, character 22 to 32</ref>).</p>
  * Working example: 
    * [[http://mpdl-text.mpiwg-berlin.mpg.de/documents/echo/la/Benedetti_1585.xml#xpointer(id(%27page7%27)/echo[1]/text[1]/div[1]/div[2]/p[1]/s[1]/range(7,42))|Benedetti, page 7, sentence 1, range 7-42]]
* XPointer to a text point (point) of an element on a page in an XML document. The result of the XPointer URL is the page and the requested text point of the element is highlighted.
  * function "point" with one parameter: 
    * position with 3 possible values
      * .0 : before the element
      * .1 : after the element
      * positive integer value: count of text characters from the beginning of all the text nodes of the element
  * Example: 
    * <p>The Ramones started up in March 1974 (see <ref target="http://mpdl-proto.mpiwg-berlin.mpg.de/tei/en/ramones_2004.xml#xpointer(id('page6')/tei[1]/text[1]/body[1]/chap[1]/p[1]/s[1]/point(22))">page 6, sentence 1, character 22</ref>).</p>
  * Working example: 
    * [[http://mpdl-text.mpiwg-berlin.mpg.de/documents/echo/la/Benedetti_1585.xml#xpointer(id(%27page7%27)/echo[1]/text[1]/div[1]/div[2]/p[1]/s[1]/point(42))|Benedetti, page 7, sentence 1, point to character 42]]

External elements of documents (e.g. user annotations) are stored separated from the document. They are positioned into the document by an XPointer with page number, xpath expression and a point. This point could have 3 values: ".0", ".1" or a positive integer (see below).

Example (external user annotation):
{{{
<object type="element"
        modificationDate="2011-03-25T11:11:11.000Z"
        uid="joe"
        documentId="/tei/en/ramones_2004.xml"
        xpointer="#xpointer(id('page6')/TEI[1]/text[1]/body[1]/chap[1]/p[1]/s[1]/point(22))">
  <content>
    <note>This is a test note with <ref target="http://slime.de">test link</ref></note>
  </content>
</object>
}}}

=== XLink ===
See [http://www.w3.org/TR/xlink/ XML Linking Language (XLink) Version 1.0].
Example: <p>The best german punk band is <bla xlink:href="http://slime.de/">Slime</bla>.</p>

XLink is not supported in TEI so far. So the MPDL project will support XLink when it is part of TEI.

=== Discussion ===

* document identifier: a persistent identifier of a document
  * http://mpdl-proto.mpiwg-berlin.mpg.de/tei/en/ramones_2004.xml 
    * Advantages
      * intuitive
      * easy to retrieve
      * compatible to XLink
      * REST like
    * Disadvantages
      * could be used once more (no id any more)
  * http://mpdl-proto.mpiwg-berlin.mpg.de/permanent/library/471122KK
    * Advantages
      * persistent id (could be used exactly one time)
      * already used in Echo-System and library
    * Disadvantages
      * counterintuitive
      * not easy to retrieve
* page number
  * http://mpdl-proto.mpiwg-berlin.mpg.de/tei/en/ramones_2004.xml#xpointer(id('page6'))
    * Advantages 
      * compatible to XLink/XPointer
      * could be interpreted also without <pb id="page6"/> in the document (through getFragment implementation)
      * REST like
    * Disadvantages 
      * if in XML document <pb/> elements are inserted or deleted afterwards many old XPointer links are broken
  * http://mpdl-proto.mpiwg-berlin.mpg.de/tei/de/ramones_2004.xml?page=6
    * Advantages
      * well-nigh compatible to XLink/XPointer
      * could be interpreted also without <pb id="page6"/> in the document (through getFragment implementation)
      * REST like
    * Disadvantages
      * if in XML document <pb/> elements are inserted or deleted afterwards many old XPointer links are broken
      * two parameters necessary (page, xpointer)
* element identifier
  * xpath expression: /tei[1]/text[1]/body[1]/chap[3]/p[1]/s[2]
    * Advantages
      * could be generated dynamically for the XML page
      * intuitive
      * full compatible to XLink/XPointer
      * easy to retrieve
      * implementation is easy and consistent (through saxon:path)
    * Disadvantages
      * if in XML document elements are inserted, updated or deleted afterwards many old XPointer links are broken
      * relative long string
  * node id: 1.1.1.3.1.2
    * Advantages
      * could be generated dynamically for the XML page
      * intuitive
      * compatible to XLink/XPointer
      * easy to retrieve
    * Disadvantages
      * if in XML document elements are inserted, updated or deleted afterwards many old XPointer links are broken
  * id attribute in XML document: <s id="47114711">...</s>
    * Advantages
      * if in XML document elements are inserted, updated or deleted afterwards only old XPointer links with deleted elements are broken
      * compatible to XLink/XPointer
    * Disadvantages
      * through upload process the document has to be modified: for each element in XML document an id attribute has to be generated, also implementation is more complex
      * if a user uses an id attribute already in his document but not consistent these id attributes have to be replaced by a new consistent id (not easy to implement)
      * the document size is bigger with all these id attribute values
      * the id is not intuitive
  * special id attribute in XML document: <s xmlNodeId="47114711">...</s>
    * Advantages
      * user could use his own id attribute in document as he like
      * if in XML document elements are inserted, updated or deleted afterwards only old XPointer links with deleted elements are broken
      * compatible to XLink/XPointer
    * Disadvantages
      * through upload process the document has to be modified: for each element in XML document an xmlNodeId attribute has to be generated, also implementation is more complex
      * the document size is bigger with all these id attribute values
      * the id is not intuitive
* point/range expression
  * point(.0) or point(.1) or range(22, 34)
    * Advantages
      * pointers point to a text portion
      * pointers point to the place before or after an element
      * is partly implemented
    * Disadvantages


=== Selection / Solution ===
* document identifier
  * http://mpdl-proto.mpiwg-berlin.mpg.de/tei/en/ramones_2004.xml 
    * Reasons
      * could be mapped to the persistent identifier, intuitive, user friendly, REST like, compatible with XPointer
* page number
  * http://mpdl-proto.mpiwg-berlin.mpg.de/tei/en/ramones_2004.xml#xpointer(id('page6'))
    * Reasons
      * compatible with XPointer
* element identifier (choice between these 2 best possible solution)
  * xpath expression: /tei[1]/text[1]/body[1]/chap[3]/p[1]/s[2] 
    * Reasons
      * no modification of the original document is done, intuitive, compatible with XPointer, dynamically generation, implementation is already mostly done 
      * an automatic repair mechanism for broken links to inside elements after document updates: no one would expect such a difficult solution for that and is also not needed normally
      * the broken link is sent to the older version of the document if a versioning system is running or an error message is given that the document has changed
* point/range expression
  * range(22, 34) or point(22), point(.0) or point(.1)
    * Reasons
      * XPointer is standard

=== Implementation ===

* new presentation mode with dynamically generated xpath identifier for all elements
  * modes: text, pureXml
    * mostly already implemented: .../interface/page-fragment.xql?...&options=withXmlNodeId
* user annotations
  * insert/update/delete user annotations: dynamic storing of annotations with an XPointer to the XML document (with user login)
    * partly implemented (login not regarded yet)
  * read user annotations: dynamic presentation of the annotations in the document presentation (insertExternalElements.xsl)
    * partly implemented
* XPointer URI's
  * implementation of a REST like URI over controller.xql: partly implemented
    * translation of the XPointer URI
    * highlighting of the requested element, text portion or text point in the element
    * different presentation modes: text, textPollux, gis, xml, pureXml
    * in .../interface/page-fragment.xql and .../page-query-result.xql
* TEI URI's
  * support URI attributes (e.g. ref(target) ptr(target)) in Echo and TEI elements: implemented
* user objects such as user queries
  * insert/update/delete user objects: dynamic storing of user queries (with user login)
    * partly implemented (login not regarded yet)
  * read user objects: show user queries after user login
    * partly implemented