= User annotations =

== Annotation tools ==
  * https://secure.wikimedia.org/wikipedia/en/wiki/Web_Annotation
  * http://sharedcopy.com/ - interesting tool wooks in different browsers. you can annotate and highlight the text
  * http://edutechwiki.unige.ch/en/Text_annotation - Different information about annotations
  * http://www.shiftspace.org/ - Firefox plugin - annotate and highlight text
  * http://www.flipbit.co.uk/jquery-image-annotation.html# - Image annotation JQUERY
  * http://annotation.semanticweb.org/tools/ - List of tools 
  * http://de.wikipedia.org/wiki/Diskussion:Ramones - Wikipedia/mediaWiki: Discussion page
  * http://de.wikipedia.org/wiki/Ramones#cite_note-Twisted1-0 - Wikipedia/mediaWiki: Notes
  * http://mpdl-system.mpiwg-berlin.mpg.de/mpdl/page-query-result.xql?document=/tei/en/Test_1789.xml&mode=text&pn=1 - Within TEI in XML document

== eXist Interface ==
External user annotations (internal TEI user annotations: see [/wiki/schema/tei-notes here]) are maintained by the interface function /mpdl/interface/external/object.xql. 
This function has 3 parameters:
* operation (possible values: read, create, update, delete)
* type (possible values: element, query)
* object (see examples below)
  * attributes
    * uid: user id (normally email address) of the operation (e.g. andy@mpiwg-berlin.mpg.de)
    * documentId: the eXist document identifier (e.g. /tei/en/Test_1789.xml)
    * xpointer: the xpointer to the position in that document (e.g.: id('page2')/TEI[1]/text[1]/body[1]/p[1]/s[3]/point(4)); see [/wiki/schema/xpointer XPointer specification]; it consists of 3 parts:
      * page number: (e.g. id('page2'))
      * XPath identifier of the XML page node (e.g.: /TEI[1]/text[1]/body[1]/p[1]/s[3])
      * text point within that node (e.g: /point(4))
  * value: if operation is create or update: the new object (e.g. <note>This is an annotation of Andy</note>)

To maintain a user annotation "at the HTML side" one needs the XPath identifier of the XML page node at which the annotation should be created/updated/deleted. This identifier is displayed by the parameter "options=withXmlNodeIds" in the interface function /mpdl/interface/page-fragment.xql. Then the output HTML document page contains an additional attribute "xmlNodeId" in all HTML nodes which are XML nodes (e.g. <span class="s" xmlNodeId="/TEI[1]/text[1]/body[1]/p[1]/s[1]">This is the first sentence of the first paragraph.</s>)


== Implementation ==
* Test-Version finished (Java, XSL script)
* To Do
  * Identify further user requirements
  * Java: perform accepetance / user test 
  * Display of a document page with external objects and with XML node ids (insertExternalElements.xsl): full redesign and new implementation
  * Bug: at one position there could be only one external user annotation so far (bug in XSL script)

== Open questions ==
* Versioning of annotations
* Discussion / Blog of each document page


== Examples ==

=== Example document ===
* [http://mpdl-system.mpiwg-berlin.mpg.de/mpdl/page-query-result.xql?document=/tei/en/Test_1789.xml&mode=text&pn=1&options=withXmlNodeIds Test document: Display of page 1 with XPath identifiers for all XML nodes]
* [http://mpdl-system.mpiwg-berlin.mpg.de/mpdl/page-query-result.xql?document=/tei/en/Test_1789.xml&mode=text&pn=2 Test document: Display of page 2 with external user annotations]

=== Read annotations ===
{{{
  http://mpdl-system.mpiwg-berlin.mpg.de/mpdl/interface/external/object.xql?
    operation=read&
    type=element&
    object=<object documentId="/tei/en/Test_1789.xml" xpointer="id('page2')"></object>
}}}
[http://mpdl-system.mpiwg-berlin.mpg.de/mpdl/interface/external/object.xql?operation=read&type=element&object=%3Cobject%20documentId=%22/tei/en/Test_1789.xml%22%20xpointer=%22id%28%27page2%27%29%22%3E%3C/object%3E Read annotations]

=== Create annotation ===
{{{
  http://mpdl-system.mpiwg-berlin.mpg.de/mpdl/interface/external/object.xql?
    operation=create&
    type=element&
    object=<object uid="andy@mpiwg-berlin.mpg.de" documentId="/tei/en/Test_1789.xml" xpointer="id('page2')/TEI[1]/text[1]/body[1]/p[1]/s[3]/point(4)"><note>This is an annotation of Andy</note></object>
}}}
Test: please don't click on: [http://mpdl-system.mpiwg-berlin.mpg.de/mpdl/interface/external/object.xql?operation=create&type=element&object=%3Cobject%20uid=%22andy@mpiwg-berlin.mpg.de%22%20documentId=%22/tei/en/Test_1789.xml%22%20xpointer=%22id%28%27page2%27%29/TEI%5B1%5D/text%5B1%5D/body%5B1%5D/p%5B1%5D/s%5B3%5D/point%284%29%22%3E%3Cnote%3EThis%20is%20an%20annotation%20of%20Andy%3C/note%3E%3C/object%3E  Create annotation]

=== Update annotation ===
{{{
  http://mpdl-system.mpiwg-berlin.mpg.de/mpdl/interface/external/object.xql?
    operation=update&
    type=element&
    object=<object uid="andy@mpiwg-berlin.mpg.de" documentId="/tei/en/Test_1789.xml" xpointer="id('page2')/TEI[1]/text[1]/body[1]/p[1]/s[3]/point(4)"><note>This is an annotation of Andy</note></object>
}}}
Test: please don't click on: [http://mpdl-system.mpiwg-berlin.mpg.de/mpdl/interface/external/object.xql?operation=update&type=element&object=%3Cobject%20uid=%22andy@mpiwg-berlin.mpg.de%22%20documentId=%22/tei/en/Test_1789.xml%22%20xpointer=%22id%28%27page2%27%29/TEI%5B1%5D/text%5B1%5D/body%5B1%5D/p%5B1%5D/s%5B3%5D/point%284%29%22%3E%3Cnote%3EThis%20is%20an%20annotation%20of%20Andy%3C/note%3E%3C/object%3E  Update annotation]

=== Delete annotation ===
{{{
  http://mpdl-system.mpiwg-berlin.mpg.de/mpdl/interface/external/object.xql?
    operation=delete&
    type=element&
    object=<object uid="andy@mpiwg-berlin.mpg.de" documentId="/tei/en/Test_1789.xml" xpointer="id('page2')/TEI[1]/text[1]/body[1]/p[1]/s[3]"></object>
}}}
Test: please don't click on: [http://mpdl-system.mpiwg-berlin.mpg.de/mpdl/interface/external/object.xql?operation=delete&type=element&object=%3Cobject%20uid=%22andy@mpiwg-berlin.mpg.de%22%20documentId=%22/tei/en/Test_1789.xml%22%20xpointer=%22id%28%27page2%27%29/TEI%5B1%5D/text%5B1%5D/body%5B1%5D/p%5B1%5D/s%5B3%5D%22%3E%3C/object%3E  Delete annotation]