From 397b82a5d1f3eda3dfc2e0b020267b1d334ff105 Mon Sep 17 00:00:00 2001
From: Alexander Watzinger <alexander.watzinger@craws.net>
Date: Sat, 28 Dec 2024 20:40:10 +0100
Subject: [PATCH] Text annotation: added manual entries

---
 openatlas/display/classes_base.py       |  2 ++
 sphinx/source/entity/source.rst         |  8 +++--
 sphinx/source/features.rst              |  5 ++++
 sphinx/source/tools/index.rst           |  1 +
 sphinx/source/tools/text_annotation.rst | 39 +++++++++++++++++++++++++
 5 files changed, 53 insertions(+), 2 deletions(-)
 create mode 100644 sphinx/source/tools/text_annotation.rst

diff --git a/openatlas/display/classes_base.py b/openatlas/display/classes_base.py
index 5f7e56770..44af57f1d 100644
--- a/openatlas/display/classes_base.py
+++ b/openatlas/display/classes_base.py
@@ -130,6 +130,8 @@ def add_note_tab(self) -> None:
 
     def add_buttons(self) -> None:
         self.buttons = [manual(f'entity/{self.entity.class_.view}')]
+        if self.entity.class_.name == 'source_translation':
+            self.buttons = [manual('entity/source')]
         if is_authorized(self.entity.class_.write_access):
             if not self.problematic_type:
                 self.add_button_update()
diff --git a/sphinx/source/entity/source.rst b/sphinx/source/entity/source.rst
index 9ae977b1b..0ff3f0381 100644
--- a/sphinx/source/entity/source.rst
+++ b/sphinx/source/entity/source.rst
@@ -16,7 +16,8 @@ Form fields
 * :doc:`/ui/name`
 * :doc:`type`
 * :doc:`/entity/artifact` - use if the source is part of an artifact
-* **Content** - a summary or the whole text of the source
+* **Content** - a summary or the whole text of the source.
+  :doc:`/tools/text_annotation` can be used.
 
 Can be linked via tabs to
 -------------------------
@@ -24,5 +25,8 @@ Can be linked via tabs to
   references
 * :doc:`reference` - link to the literature the source is documented in, e.g.
   editions of charters or secondary sources
-* **Translation** - add translations of the source or a comment
+* **Text** - add translations or similar to the source
 * :doc:`file`
+
+Text annotation
+---------------
diff --git a/sphinx/source/features.rst b/sphinx/source/features.rst
index 937f20018..4e6a804e7 100644
--- a/sphinx/source/features.rst
+++ b/sphinx/source/features.rst
@@ -70,6 +70,11 @@ Image Annotation
 With enabled IIIF it is possible to annotate images and link the annotation to
 entities via the :doc:`/tools/image_annotation` feature.
 
+Text Annotation
+---------------
+Text parts of sources can be annotated and linked to entities via the
+:doc:`/tools/text_annotation` feature.
+
 Data Exchange
 -------------
 OpenAtlas offers various possibilities to exchange data with other systems or
diff --git a/sphinx/source/tools/index.rst b/sphinx/source/tools/index.rst
index 5e1ef2e34..fd19ca9ea 100644
--- a/sphinx/source/tools/index.rst
+++ b/sphinx/source/tools/index.rst
@@ -8,6 +8,7 @@ Tools
    profile
    notes
    image_annotation
+   text_annotation
    map
    network
    anthropological_analyses
diff --git a/sphinx/source/tools/text_annotation.rst b/sphinx/source/tools/text_annotation.rst
new file mode 100644
index 000000000..19ecfdd18
--- /dev/null
+++ b/sphinx/source/tools/text_annotation.rst
@@ -0,0 +1,39 @@
+Text annotation
+===============
+
+.. toctree::
+
+The text annotation feature allows for marking text in a
+:doc:`/entity/source` (or source text) adding a comment and/or link to an
+entity. In that way the mention of a person, place, event ... can be linked to
+entity in OpenAtlas.
+
+Usage
+-----
+A text can be annotated when when adding or updating a :doc:`/entity/source`
+(or source text) with following steps:
+
+* Mark the specific text part in the source with the left mouse button
+* Click on the **Annotate** button above the text field
+* Select the entity which is releated to the annotation and/or
+* Add a comment
+* Click on add
+* Press the save button of the form to submit it
+
+After that the text annotations should already be visible in the source detail
+view:
+
+* Links to other entities are displayed
+* With mouse over you can read the comments
+
+Limitations
+-----------
+This is still considered an experimental feature and will be tested and
+improved. Feedback about it is welcome.
+
+**Current limitations**
+
+* Only entities that are already linked with the source can be chosen for
+  annotation
+* It is not possible to annotate over line breaks
+* Labels and messages of the annotation tool are available only in English