Add user-specific comment field

koppor commented 2 years ago

Setting: As a research group, the BibTeX data is collaboratively managed. Some contributors might comment on a BibTeX entry (instead of commenting into the PDF). One might want to have tooling support to know from which contributor which comment comes from. (CloudRef offers that feature for PDF comments: https://github.com/JabRef/cloudref)

Implementation Hints

Currently, comments are stored as follows:

@InBook{demo,
  author  = {Author Test},
  comment = {comment by user koppor: One should really read this paper},
}

New storage format:

@InBook{demo,
  author  = {Author Test},
  comment-koppor = {One Should really read this paper},
}

No migration of existing comment fields should be done
The field comment should still be displayed
All comments of all users are displayed
Only comments of the current user are allowed to be edited
The suffix for the comment field name can be retrieved by OwnerPreferences#getDefaultOwner().
Advanced: Other comments are displayed with a lock symbol. One can click on the lock to be able to edit the comment

Side note: We have user-specific file directory, user- + host-specific aux file, now it's time for user-specific comment field. We should re-use the functionality to determine the username

@Comment{jabref-meta: fileDirectory-koppor-DESKTOP-KAK953S:c:\\temp;}

Alternative Implementation Possibilities

Following possibilities were discussed, but neglected:

Enforce manual process that each contributor puts his initials in front
Use git blame (see #532)

Siedlerchr commented 1 year ago

Implementation idea: Use UnkownField as basis

The user can be obtained from the preferences: preferencesService.getFilePreferences().getUser()

koppor commented 1 year ago

For the following explanation, userid holds the current user name (via OwnerPreferences#getDefaultOwner())

Cases

Case 1: No comments

@Misc{case1,
}

Case 2: General comments

@Misc{case2,
  comment = {general-comment},
}

Case 3: One user-specific-comment

@Misc{case3,
  comment-userid = {userid's comment},
}

Case 4a: Two user-specific-comments - one by userid

@Misc{case4a,
  comment-userid = {userid's comment},
  comment-otheruserid = {otheruserid's comment},
}

Case 4b: Two user-specific-comments - none by userid

@Misc{case4b,
  comment-otheruserid = {otheruserid's comment},
  comment-veryotheruserid = {verotheruserid's comment},
}

Case 5a Two user-specific-comments and general comments - one by userid

@Misc{case5a,
  comment = {general-comment},
  comment-userid = {userid's comment},
  comment-otheruserid = {otheruserid's comment},
}

Case 5b Two user-specific-comments and general comments - none by userid

@Misc{case5b,
  comment = {general-comment},
  comment-otheruserid = {otheruserid's comment},
  comment-veryotheruserid = {verotheruserid's comment},
}

UI

The content of the tab "Comments" needs to be modified.

This tab should list all comments. It should offer a button to add or to modify a comment:

Case 5a

Here, the entry already has a comment of the userid.

```plantuml @startsalt { General | "general-comment" userid | "userid's comment" | [delete] otheruserid | "otheruserid's comment" } @endsalt ```

Case 5b

Here, the current user did not put any comment. Thus, "Add new comment" is displayed at the bottom". If pressed, a new comment field is added, and the focus is in the new text field

```plantuml @startsalt { General | "general-comment" otheruserid | "otheruserid's comment" veryotheruserid | "veryotheruserid's comment" . | [ Add new comment ] } @endsalt ```

After pressing of the button:

koppor commented 1 year ago

TLDR: Try "Second Implementation Proposal" and see if it works. If not, go for "First Implementation Proposal".

First Implementation Proposal

The Java code needs to be extended by a class "CommentsTab". See OptionalFieldsTab.java for an example of a generic tab implementation. MathSciNetTab.java is another tab, which offers a kind of special functionality. It shows only if a MathSciNetId is present.

As a first step, one could focus on showing and editing functionality (and ignore the need for an addition. As workaround, that can then be done using the bibtex source tab).

Implement determineFieldsToShow in the new CommentsTab class similar to OtherFieldsTab.java. Just show user comment fields there.

Background

The current implementation is too generic to be used.

Currently, in the preferences, the user determines that comments should be rerendered in a tab.

This is then handled at EntryEditor.java.

        // General fields from preferences
        for (Map.Entry<String, Set<Field>> tab : entryEditorPreferences.getEntryEditorTabList().entrySet()) {
            entryEditorTabs.add(new UserDefinedFieldsTab(tab.getKey(), ...;
        }

This is how the tab "Comments" appears.

Second Implementation Proposal

Based on the knowledge gained from "Background", this generic solution could be reused. Instead of allowing fixed strings in the preferences, one could allow glob patterns. Then Comment:comment;comment-* could be a valid entry. And JabRef "magically" collects all comments in the tab "Comments".

This, however, has the drawback that no new comment can be added. Nevertheless, during loading, there could always be an empty field comment-userid be created. AFAIK during writing, JabRef skips empty fields. Thus, this could be the most clean solution.

koppor / jabref