Open JonatanSahar opened 1 year ago
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
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.
Perhaps an :open-no-display
could be helpful?
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:
Points 2. and 3. require that Ebib be given a buffer.
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:
This goes along with my suggestion here ('Concerning 2') that the notes backend should return different values in different circumstances:
t
or nil
depending on the implementation) means that the backend has handled displayThis 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.)
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
ornil
depending on the implementation) means that the backend has handled display
:+1:
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...
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?
@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?
Seems much of the recent back-and-forth is about ebib.
Indeed. :slightly_smiling_face:
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.
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?
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
.
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.
But I assume Citar has a public API for opening and creating notes?
It does; it's a key feature.
:+1:
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. :slightly_smiling_face: 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
.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.
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.
https://github.com/emacs-citar/citar/blob/07d2a63c99fe35cbd468f8e6a322de05f1a29469/citar.el#L445
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]
@localauthor @pprevos - we're discussing possibility of a small breaking change to the notes API. Any input?
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?
: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.
@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.
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!