Comment functionality

[simongray]

It must be possible to attach comments to documents, preferably linked to specific paragraphs.

• how should it work?
• how should it look?
• what tech to use, Asami or sqlite?

[simongray]

Since this will be demoed to Carlsberg in September/Oktober, it should be finished by then.

[simongray]

I guess it could be integrated with #28.

[simongray]

The general idea is to allow comments/notes at the paragraph level, essentially just expanding how notes are already marked up in the TEI files. Notes are used in the following way in the TEI files:

• Target is unspecified (whole document):
  • <note xml:id="n1" resp="hand/machine" hand="#np56" place="above">.
• Target is a facsimile/page:
  • <note xml:id="n1" target="#acc-1992_0005_024_Holt_1210_001.tif" place="top" resp="machine" hand="#np56">.
• Target is a paragraph:
  • <note xml:id="n5" target="#p8" resp="Mads Nielsen" type="transcribernote">

It makes sense to display generated notes in the same way using the same markup. In that way, the same components can be reused for the TEI notes and the comments and the appearance is also unified.

---

The most obvious way to handle notes is to have a [:summary [:details ...]] setup for them, where the document- and page-wide notes are opened by default, while paragraph notes are closed by default. All notes are listed in order within the [:details ...] as list items.

New notes are created by clicking on a "new note" symbol placed in various convenient places, e.g. in the margins of a paragraph or right after the page ends.

---

Notes are represented as entities related to the relevant entities in the Asami graph, e.g. document IDs or facsimile IDs.

;; document notes
[?note :note/target ?tei-file]
[?note :note/body ?body]
[?note :note/author ?author]

;; page notes
[?note :note/target ?facsimile]
[?note :note/body ?body]
[?note :note/author ?author]

In the case of paragraph-level notes, a special paragraph attribute is used e.g.

;; paragraph note
[?note :note/target ?facsimile]
[?note :note/body ?body]
[?note :note/author ?author]
[?note :note/paragraph "#p8"]  ; important bit

[simongray]

Aside from text notes, we also need to support adding new entities as :document/relevant-for relations!

This further complicates things as we need to represent this in the data in a way that it will work in searches, while also keeping track of who added what. It also necessitates having to port the search UI to the comments in order to reuse it for adding entities.

[simongray]

I asked @quoll about combining in-memory and persistent storage in the asami channel on Clojurians slack and she directed me here: https://github.com/quoll/asami/blob/main/src/asami/wrapgraph.cljc

[simongray]

Since my intended functionality doesn't entirely align with the functionality in Asami, it might be a better idea to keep the graphs separate and develop multi-graph querying similar to what I did with DanNet.

When only the persisted graph is relevant, only this graph is queried. When transacting, only the persisted graph is used, except for the initial bootstrap of the in-memory graph.

[simongray]

Data architecture update

Since it is possible to use anything data structure as the object, the simplest solution might simply be to use and then have all of the information inside that map, e.g.

[?tei-file :note {:author    ?author
                  :target    ?target
                  :body      ?body
                  :timestamp ?timestamp}]

This will work for comments, but it will not work for querying tei files directly by :relevant-for.

It's also perfectly possible that this is just a minor performance improvement and that I better stick with atomised triples and reification in all cases.

[simongray]

Working on the frontend UI first of all, trying to get things to a usable state.

Making paragraphs clickable was quite easy, however, there is one easy which has more to do with the fact that paragraphs are sometimes split across pages, resulting in paragraph targets sometimes being e.g. p2-2 as opposed to p2: http://localhost:8080/app/reader/acc-1992_0005_030_Western_0120-tei-final.xml

In those cases we want to extract and cite the entire paragraph, ignoring page breaks, and keeping the actual target found in the TEI file, e.g. p2. When the target has been established, the comment section performs a dynamic cuphic search to select just the cited paragraph and displays this section along with a text field for adding comments.

[simongray]

The endpoints/add-comment-handler returns all comments for the specific entity (e.g. TEI document) as its result. I have deliberately left the implementation such that any entity can be commented, although I don't think I will get around to allowing anything other than TEI documents.

A comment can have a specific target—or no target at all, in which case the entity itself is the target. The frontend decides where and how to display the comments based on the mix returned. I need to figure out a good design eventually, but for now I am just focused on getting the backend machinery working.

Since there is one comment with a unique ID per combination of user, entity id, and target. Resubmitting to endpoints/add-comment-handler will update this comment.

Comment threads

In future, the target can perhaps be other comments, beginning actual comment threads. This would make queries stay simple, since all comments are still related directly to the document.

Another option is to have the entity id of the comment be that of another comment. That would make the query currently in use unable to fetch all comments (requiring additional fetches), although it would also make things more performant for heavy discussions.

I think using target is the better choice for Glossematics.

[simongray]

What about deletion?

One aspect of allowing deletion of comments is that the threads will be orphaned. It might be a better choice to not allow this and simply treat a deletion event as removing the content of the comment, i.e. "" or nil. For this reason, endpoints/add-comment-handler can be reused to delete comments too.

[simongray]

This issue now also depends on #89 since the ID format for bookmarks has changed.