Make notes infrastructure more flexible, to allow user's external integrations

[Hugo-Heagren]

I've started using org-roam for note-taking, and citar for dealing with bibliographies while writing. They play very nicely together -- I've got a setup now where navigating to an entry's note from citar opens the relevant note in org-roam (or creates one, using org-roam's capture mechanism, if it doesn't already exist).

I'd like to be able to synchronise this functionality with ebib. That is, I'd like ebib to behave the same way: opening or capturing the relevant note when I use ebib's built-in notes functionality.

I'm happy to write the code and make a PR, but I'd like some input on the overall strategy.

Broadly I think that the user should be able to customise notes behaviour by customising various variables, which are set to functions (that is, a similar approach to ebib-notes-extract-text-function, but for other functionality as well). These functions should take standardised arguments, and return standardised types of output. Then "front-end" functions like ebib-popup-note will be implemented by calling those functions.

All the current behaviour can be retained by keeping it in the default function for each of those variables (which most users will probably be happy with).

I think the following functionality could/should be customisable this way:

• telling whether an entry has a note
• opening(/creating) an entry's note
• extracting an entry's note's text (already done)
• deleting an entry's note

This roughly mirrors (and is heavily inspired by) citar's approach, where there are functions to:

• test whether an entry has notes
• open a given note
• return list of notes for an entry
• create a note

I understand this would be a big change, potentially with significant backward-incompatibility, so what do you think?

[Hugo-Heagren]

I haven't looked at this for a while, but I was thinking about it today. One of the big problems with this idea is that breaks quite a lot from the previous setup, and (understandably!) lots of users who rely on that setup might not want that.

Here's a rough guide to a possible implementation. I'm mostly just putting it here so that I can refer to it if I ever come back to this project...

Have four variables:

• ebib-notes-has-note: set to a function which takes a key and returns non-nil if the entry has a note
• ebib-notes-open-note: set to a function which takes a key and opens the notes for that key
• ebib-notes-create-note: set to a function which takes a key and creates the notes for that key
• ebib-notes-extract-note (possibly): set to a function which takes a key and extracts the note text for that key

Now for backwards compatibility. For each variable, write such a function which checks the old variables like ebib-notes-storage, and mimics the previous behaviour. Then deprecate these variables so that users know the newer system is the standard (but they can still use these functions to get exactly the same behaviour as before).

If we wanted to support the possibility of having more than one note per entry (like citar does), we could split ebib-notes-open-note into:

• ebib-notes-get-notes: set to a function which returns a note object (can be anything which is not a list) or list of such.
• ebib-notes-open-note: (note singular note) set to a function which takes a single note object and opens it correctly.

Possible issues:

• what is the API for opening notes? Should these functions return a buffer? What about dealing with org-capture (which pops up a buffer in a different window...)
• if we do multiple notes, we need a prompt to choose between them
• If the notes object can be anything, and we need a prompt, then we will also need a (user customisable) formatter which produces a string (to be used a candidate in the prompt) from the original note object.

[fernandodemorais-jf]

Hello @Hugo-Heagren,

+1 to your idea! We, now a some time ago, discussed an integration between denote and ebib.

But reading the code of this package, I realized that small changes should be made for smoother and more complete integration. Your proposed system, in my view, is just what it needs.

You have some prototype code for this proposed implementation, that you can share, so I can test it with an denote integration in mind?

Thanks!

[Hugo-Heagren]

You have some prototype code for this proposed implementation, that you can share, so I can test it with an denote integration in mind?

Unfortunately I don't yet -- I've been working on other things lately and this taken a bit of a back seat. As/when I do build something I will post it here and tag you, though it might be some time I'm afraid...