add an "other window'/"other frame" option for opening notes

[JonatanSahar]

Is your feature request related to a problem? Please describe.
I often want to review a note I have on a reference while writing text including that reference (by pressing RET on the cite link etc). atm, the note replaces the the buffer of the text I'm working on.

Describe the solution you'd like
I'd like to have the possibility of opening the note in another window/frame

Describe alternatives you've considered
I can always split the window first, and then access the cite link

Thanks!

[bdarcus]

I agree it makes sense, but am not really sure how to do that, or if it should really be the domain of this package. If you're in an org buffer, isn't that an org config issue?

Another wrinkle is it may be an org-roam or denote etc buffer.

Related:

https://emacs.stackexchange.com/questions/48683/open-org-mode-links-to-info-in-different-window

[swflint]

This sort of thing is related to the problem that we're having in joostkremers/ebib#301. There, we're trying to use citar--select-resource and (citar--get-notes-config :open) to get a buffer to display, though it's unclear if we can expect a buffer from the notes opener.

[swflint]

Perhaps an :open-no-display could be helpful?

[joostkremers]

I agree it makes sense, but am not really sure how to do that, or if it should really be the domain of this package. If you're in an org buffer, isn't that an org config issue?

I'm not a Citar user and I'm not familiar with its source code, or its design goals, so I can't definitively say, but in general, I'd say that it's the package that provides the interactive command that should also take care of displaying the buffer. But for that to be possible, it needs to be given a buffer, but it seems that that's not guaranteed to happen with Citar.

We're in the process of making Ebib's note-handling more open, i.e., making it easier to plug in a user's preferred note-taking system, and this is a problem we're running into. Ebib basically needs three things:

1. Check if a BibTeX entry has a note.
2. Display a note without selecting the buffer.
3. Opening a note for editing / creating a new note, which involves displaying the note buffer and selecting it.

Points 2. and 3. require that Ebib be given a buffer.

[Hugo-Heagren]

in general, I'd say that it's the package that provides the interactive command that should also take care of displaying the buffer

I agree, in general, but the general is doing some heavy lifting here. I think it's likely many users will want to use org-capture based workflows, and (for better or worse) there is no way to do so without having the notes backend handle display (and not citar/ebib).

So I think that it would be good to design a system flexible enough to accomodate both:

• ebib/citar getting a buffer and handling display
• ebib/citar knowing that the notes backend has handled display

This goes along with my suggestion here ('Concerning 2') that the notes backend should return different values in different circumstances:

• a buffer return means that the driver app (ebib/citar) needs to handle displaying the buffer
• a special value (e.g. t or nil depending on the implementation) means that the backend has handled display

This system could easily be extended too. For example, if needed, a window return means the buffer is displayed in that window but the window is not selected (and the driver app has to do that). I'm not sure who would need this, but it's the sort of thing which would be easy to do if necessary. In the extreme case, this whole return-val/behaviour pattern could be encoded in a customisable user var (an alist mapping predicates on the return value to handler functions) so users could write their own handlers if need be. I think this is probably unnecessary, but it's the sort of thing you could do.

(Of course, it would also be really nice if the system allowed for different kinds of display, in other-window, other-tab, etc. but that's a separate thing.)

[joostkremers]

So I think that it would be good to design a system flexible enough to accomodate both:

• ebib/citar getting a buffer and handling display
• ebib/citar knowing that the notes backend has handled display

Yes, absolutely. It's what Ebib already allows when creating a note (because you can use org-capture for that). It would be easy to allow that for opening a note as well.

• a buffer return means that the driver app (ebib/citar) needs to handle displaying the buffer
• a special value (e.g. t or nil depending on the implementation) means that the backend has handled display

👍

Ebib uses nil, BTW. Makes it easy to write something like:

(if-let ((buffer (funcall ebib-notes-backend :open-note key)))
    (pop-to-buffer buffer))

(Of course, it would also be really nice if the system allowed for different kinds of display, in other-window, other-tab, etc. but that's a separate thing.)

That's what display-buffer-alist is for, isn't it? Whether it's the front-end or the back-end that handles displaying the notes buffer, they should use display-buffer and friends...

[bdarcus]

Seems much of the recent back-and-forth is about ebib. What, if anything, do we need here?

Does this impact our note API at all?

[bdarcus]

@swflint

we're trying to use citar--select-resource and (citar--get-notes-config :open) to get a buffer to display, though it's unclear if we can expect a buffer from the notes opener.

They are both "private" functions, so we didn't anticipate other packages using them.

@aikrahguzar @roshanshariff - any thoughts on this?

[joostkremers]

Seems much of the recent back-and-forth is about ebib.

Indeed. 🙂

What, if anything, do we need here?

Well, for Ebib it would be very helpful if there were guarantees about the return values of the functions in citar-notes-sources, esp. :open and :create. Judging by the doc string, those two don't require a specific return value.

Does this impact our note API at all?

Currently, Ebib assumes that :open returns a buffer and that Ebib should display it and can decide whether to select it or not; and that :create returns a buffer that Ebib should then display and select. :create can also return nil, in which case Ebib assumes that the back-end displays and selects the buffer.

The design on Ebib's side is not set in stone, so I'm open to alternatives.

[joostkremers]

They are both "private" functions, so we didn't anticipate other packages using them.

But I assume Citar has a public API for opening and creating notes? (Or is that a silly assumption? Like I said, I don't use Citar.)

Or interactive functions?

[bdarcus]

But I assume Citar has a public API for opening and creating notes?

It does; it's a key feature.

Aside: I was noting that just to explain; not to suggest I'm opposed to making any changes.

Here's an example of its use in citar-org-roam.

https://github.com/emacs-citar/citar-org-roam/blob/82d47b5df1926627f56a09055c69b49b31cbbb9f/citar-org-roam.el#L75

So a possibility is we slightly change that API in ways that are more flexible (specifically, making the :create and :open function return types specific along the lines that you have), and works for your case.

[joostkremers]

But I assume Citar has a public API for opening and creating notes?

It does; it's a key feature.

👍

Aside: I was noting that just to explain; not to suggest I'm opposed to making any changes.

I didn't take it that way. 🙂 I just don't want to give you the impression I'm demanding changes to Citar.

Here's an example of its use in citar-org-roam.

https://github.com/emacs-citar/citar-org-roam/blob/82d47b5df1926627f56a09055c69b49b31cbbb9f/citar-org-roam.el#L75

So a possibility is we slightly change that API in ways that are more flexible, and work for your case.

Our difficulty is that we don't want to define functions for the actions that Citar's API defines (:hasitems, :open, :create, etc.) because we assume that the user has already defined them. (Or has installed a package that defines them.) We would like a way to call the existing :open function and then either handle the buffer display and selection ourselves, or be confident that that's already been done.

[bdarcus]

Our difficulty is that we don't want to define functions for the actions that Citar's API defines (:hasitems, :open, :create, etc.) because we assume that the user has already defined them. (Or has installed a package that defines them.) We would like a way to call the existing :open function and then either handle the buffer display and selection ourselves, or be confident that that's already been done.

Maybe we also add public variants of those functions that correspond to the updated, tighter, API requirement?

It seems a little odd, now that I look at it, that the default notes config for citar uses those "private" functions.

citar/citar.el

Line 445 in 07d2a63

:create #'citar-file--create-note

So the updated API description could be something like (feel to suggest improvements; this is just a strawman):

  :open function that, when given a note ID, returns a buffer ...

  :create function that, when given a note ID, creates new note if not present [not sure here]

[bdarcus]

@localauthor @pprevos - we're discussing possibility of a small breaking change to the notes API. Any input?

[pprevos]

Thanks for the head-up.

I am not fussed with changes, as long as I know how to hook into Citarwith Denote. Is there a version to test yet?

[joostkremers]

  :open function that, when given a note ID, returns a buffer ...

  :create function that, when given a note ID, creates new note if not present [not sure here]

This is what Ebib currently expects:

:open      Function that, when given a note ID, opens the note and returns
           the buffer containing it. The buffer should not be displayed nor
           selected. (The front-end does that, if necessary.) If opening the
           note fails, this function should silently fail, not raise an error.

:create      Function that, when given a note ID, creates a new note and
             returns the buffer without displaying or selecting it. Alternatively,
             it can display and select the buffer and return nil. If note creation
             fails, this function can raise an error.

If that sounds a little arbitrary, then you're probably right. Historic reasons... Especially the error handling is unfortunate, I think. So I'm not against making changes to Ebib.

Conceptually Ebib requires these actions (apart from :has-note):

:get-buffer     Like :open described above

:edit     Like :create above, but for existing notes 

:create     As described above

Ebib currently collapses :get-buffer and :edit into :open, which is unfortunate, because :edit should be allowed to raise an error, and because for :edit the buffer should be displayed and selected, unlike for :get-buffer.

:edit and :create could in principle be collapsed, because the distinction is just whether the note already exists, which the back-end knows. (The distinction between :get-buffer and :edit lies in what the front-end wants to do with the note, which is why it's less practical to collapse them.)

Obviously, I'm reasoning from my perspective, which is based on what Ebib currently offers and what it would need in order to interface with other notes back-ends without changing any of its front-end code. That shouldn't be taken as a requirement, though.

[bdarcus]

@pprevos

Is there a version to test yet?

No. If and when there is, it will be linked here.

Obviously, someone will have to dig into the code and figure out what would be involved in the suggested changes. I suspect it should be fairly trivial, but haven't looked at it myself yet.