Add bibtex-actions-at-point

[ilupin]

This PR allows the bibtex key at point as initial input. Actions are available through bibtex-actions-at-point with bibtex-actions-open as the default.

[bdarcus]

Thanks for this!

First, I'm a little confused on the intial input connection. How is this supposed to work from a user POV?

Second, can you please look at #132, and consider:

1. If you know something about capf, how I get that working properly? I'm stuck on one thing.
2. How you would reconcile these two? Obviously this is a general at point function, while Add bibtex-actions-complete-key-at-point #132 is a specific one for completing at-point, but could be confusing. Maybe this would be better called bibtex-actions-open-at-point, to mirror bibtex-actions-complete-key-at-point?

Also, see the CI docstring warnings.

[bdarcus]

cc @apc @publicimageltd

[publicimageltd]

Nice idea, but somehow the way this additional function is realized strikes me as odd. We already have a plethora of functions which can be bound to any key, plus the real action would be actually hidden in the value of bibtex-actions-default-action.

The core of the proporal is to create an initial input from the thing at point, so why not generalize this function? If we are on a key, just add that key to the initial input - for any function. In such a more generalized form, it could be also used for tools like embark.

[ilupin]

First, I'm a little confused on the intial input connection. How is this supposed to work from a user POV?

M-x bibtex-actions-at-point will check if a citation key exists at current cursor position by bibtex-completion-key-at-point, which depends on bibtex-completion-key-at-point-functions. If some key is found, it is used as the initial input and only bibtex items matching the key are shown in the minibuffer (usually there is only one). If not, the command shows all bibtex items and behaves like other bibtex-actions-* commands.

Second, can you please look at #132, and consider:

I don't know much about how to implement a completion-at-point-function. This PR just reuses bibtex-completion-key-at-point to do the hard work, and #132 is a more complicated feature.

---

Nice idea, but somehow the way this additional function is realized strikes me as odd. We already have a plethora of functions which can be bound to any key, plus the real action would be actually hidden in the value of bibtex-actions-default-action.

I have been using ivy-bibtex before. ivy-bibtex has one main command ivy-bibtex, which pre-selects citation key at point, and all other functions (e.g. insert/open/...) are available as actions on selected item. I think a similar function would be convenient when using bibtex-actions + embark.

The core of the proporal is to create an initial input from the thing at point, so why not generalize this function? If we are on a key, just add that key to the initial input - for any function. In such a more generalized form, it could be also used for tools like embark.

I'm not sure if it is good to add the key at point for all bibtex actions. When a user calls a bibtex action interactively, the key at point should be useful for bibtex-actions-open-*, but not for bibtex-actions-insert-*.

[publicimageltd]

I'm not sure if it is good to add the key at point for all bibtex actions. When a user calls a bibtex action interactively, the key at point should be useful for bibtex-actions-open-*, but not for bibtex-actions-insert-*.

Sounds like a good solution to me! As said, this also preserves the possibility to use the"parser" which recognize a citation key at point for embark.

[bdarcus]

First, I'm a little confused on the intial input connection. How is this supposed to work from a user POV?

M-x bibtex-actions-at-point will check if a citation key exists at current cursor position by bibtex-completion-key-at-point, which depends on bibtex-completion-key-at-point-functions. If some key is found, it is used as the initial input and only bibtex items matching the key are shown in the minibuffer (usually there is only one). If not, the command shows all bibtex items and behaves like other bibtex-actions-* commands.

I just tested this, and it doesn't work for me; no initial input is set.

Not sure it make any difference, but I'm testing the new org-cite syntax, which is high priority for me to support.

Example:

Text with a citation: [cite:@mcneill2011].

I have been using ivy-bibtex before.

What do you use to author documents? Latex, markdown, or org?

ivy-bibtex has one main command ivy-bibtex, which pre-selects citation key at point, and all other functions (e.g. insert/open/...) are available as actions on selected item. I think a similar function would be convenient when using bibtex-actions + embark.

I made a design decision early on not to follow the ivy/helm-bibtex approach of a single command, in part to give us all more flexibility.

But @apc earlier was asking for essentially a configurable default "open" command. See, for example, #121 (comment), and subsequent discussion.

Do note that I have followed helm/ivy-bibtex where it makes sense, and diverged in other cases.

I'm not sure if it is good to add the key at point for all bibtex actions. When a user calls a bibtex action interactively, the key at point should be useful for bibtex-actions-open-*, but not for bibtex-actions-insert-*.

Yes.

PS - if we do merge this, I just realized we may want to configure the prompt for each command, so that one knows which one is active.

[ilupin]

I just tested this, and it doesn't work for me; no initial input is set.

Not sure it make any difference, but I'm testing the new org-cite syntax, which is high priority for me to support.

Example:

Text with a citation: [cite:@mcneill2011].

bibtex-completion-key-at-point-functions doesn't support org-cite syntax currently, the following code is needed for org-cite. You can also test it in latex/bibtex mode buffers.

(defun bibtex-completion-get-key-org-cite ()
  (when (eq major-mode 'org-mode)
    (let ((elt (org-element-context)))
      (if (eq (car elt) 'citation-reference)
          (org-element-property :key elt)))))

(add-to-list 'bibtex-completion-key-at-point-functions
             'bibtex-completion-get-key-org-cite)

What do you use to author documents? Latex, markdown, or org?

latex and org

I made a design decision early on not to follow the ivy/helm-bibtex approach of a single command, in part to give us all more flexibility.

But @apc earlier was asking for essentially a configurable default "open" command. See, for example, #121 (comment), and subsequent discussion.

Do note that I have followed helm/ivy-bibtex where it makes sense, and diverged in other cases.

Adding a command bibtex-actions-at-point, which is similar to ivy-bibtex, doesn't mean that we have to use it. Other commands are still available and bibtex-actions doesn't lose anything.

But I don't insist on adding bibtex-actions-at-point or a default "open" command, because it is easy to add them to personal configuration.

As pointed out by @publicimageltd, the core of this PR is allowing bibtex-actions-read use the citation key at point as initial input. Other code can be removed from this PR if you perfer. What do you think?

[bdarcus]

I just tested this, and it doesn't work for me; no initial input is set.
Not sure it make any difference, but I'm testing the new org-cite syntax, which is high priority for me to support.
Example:

Text with a citation: [cite:@mcneill2011].

bibtex-completion-key-at-point-functions doesn't support org-cite syntax currently,

OIC. I took a look again at the bibtex-completion code for this, and now understand how it all works.

Also works as expected for me in latex-mode.

... the following code is needed for org-cite. You can also test it in latex/bibtex mode buffers.

(defun bibtex-completion-get-key-org-cite ()
  (when (eq major-mode 'org-mode)
    (let ((elt (org-element-context)))
      (if (eq (car elt) 'citation-reference)
          (org-element-property :key elt)))))

(add-to-list 'bibtex-completion-key-at-point-functions
             'bibtex-completion-get-key-org-cite)

Seems we need to submit a PR for this for bibtex-completion also, as org-cite will be the future of citations in org-mode.

I notice also it doesn't recognize pandoc citations in org.

Adding a command bibtex-actions-at-point, which is similar to ivy-bibtex, doesn't mean that we have to use it. Other commands are still available and bibtex-actions doesn't lose anything.

Yeah, I'm just trying to think forward.

For sake of argument, let's say org-cite is merged to master next week (at it's current pace, that's not unreasonable).

Does that have any implications for this at all?

https://code.orgmode.org/bzg/org-mode/src/wip-cite-new/lisp/oc.el

But I don't insist on adding bibtex-actions-at-point or a default "open" command, because it is easy to add them to personal configuration.

As pointed out by @publicimageltd, the core of this PR is allowing bibtex-actions-read use the citation key at point as initial input. Other code can be removed from this PR if you perfer. What do you think?

I'm not sure. When I'm asking questions, I'm legitimately interested in feedback to help think it through together. :-)

Part of my uncertainty is I don't understand how embark might fit here. Do either of you, @ilupin or @publicimageltd?

[bdarcus]

I got word today of a sudden death in the family that may slow down my decision-making on the details here. But that will give time for others to weigh in as well.

In any case, I support this PR in principle; thanks again.

In related news, I've decided to make the function in #132 specific to org-cite as well, and asked for help on it on the org-mode list.

So we could end up with two org-cite-specific at-point functions.

[bdarcus]

Actually, WDYT about adding that bibtex-completion-get-key-org-cite function you included above to the PR @ilupin?

We can always remove it if it gets integrated in bibtex-completion.

[bdarcus]

Actually, WDYT about adding that bibtex-completion-get-key-org-cite function you included above to the PR @ilupin?

Though easy enough to add once org-cite is actually merged.

[bdarcus]

@ilupin - it's taken me a bit to understand org-cite follow processors, but I think I have it.

It allows us to wrap the same function here in such a way that a user could call that function directly from the buffer using org-open-at-point. In other words, if point is on a citation, and you do M-x org-open-at-point, will open the pdfs, links, etc. of all its reference directly.

Something like this (though there's probably a bug, because I'm currently unable to test it) should be all that's necessary:

https://gist.github.com/bdarcus/9e93547c91da8923897b25b31f230b1b

I'd probably want something like a hydra menu to bind a few command options there, unless embark can do that sort of thing?

[publicimageltd]

I'd probably want something like a hydra menu to bind a few command options there, unless embark can do that sort of thing?

I'd use embark. It's easy. Here's an example to use embark to open links:

;;; First, define a function which identifies the thing at point:
  (defun embark-target-org-link-at-point ()
    "Teach embark to recognize org links at point."
    (when (org-in-regexp org-link-any-re)
     ;; return a list: (category item)
      (cons 'org-link (match-string-no-properties 0))))
;;; Then register it as a 'target finder':
  (add-to-list 'embark-target-finders
               #'embark-target-org-link-at-point)
;;; Now define a target specific keymap....
  (embark-define-keymap embark-org-link-map
    "Keymap for org links."
    ("RET" org-open-at-point-global)
    ("o" some-other-function-which-is-not-defined-in-that-snippet))
;;; ...and hook it into embark:
  (add-to-list 'embark-keymap-alist
               '(org-link . embark-org-link-map))

[bdarcus]

I'd use embark. It's easy.

Great; this is the piece I didn't know!

Thanks!

So we could tweak the new org-cite at-point function to turn it into such a "follow" processor, then add an example embark config to bind additional commands for that to the README?

How does embark then work at point? Just use a different keybinding to bring up the command list?

[publicimageltd]

So we could tweak the new org-cite at-point function to turn it into such a "follow" processor, then add an example embark config to bind additional commands for that to the README?

Yes. Though it would be cool, of course, to have some kind of automatic plug in, e.g. with eval-after-load.

How does embark then work at point? Just use a different keybinding to bring up the command list?

Exactly. You call embark-act in the buffer, then there is a feedback in the minibuffer ("ACT"; but I think that's even optional); and then you can press some keys (or use C-h to get a list of options to choose from via completion). That's all. It's less intrusive than a hydra and due to the abstraction of "target finders", more general. You can configure it to be rather verbose, of to remain as silent as possible.

The function chosen by the user is called with the "calling" point current, as far as I understand, so you can use all functions which e.g. scan the buffer, etc.

[bdarcus]

The function chosen by the user is called with the "calling" point current, as far as I understand, so you can use all functions which e.g. scan the buffer, etc.

So the "follow" processor by definition works on org-cite objects in buffer.

The new bibtex-actions-at-point function is basically, with a minor tweak or two, just such a follow processor. So it will extract the keys from the object, and pass it to the default function.

I just want to bind a keymap to that, such that if point is on an org citation or citation-reference, embark with allow us to directly call the relevant functions in the same way.

That'll work then?

Or does what you suggest mean we need dedicated at-point command variants for each one?

[ilupin]

I just want to bind a keymap to that, such that if point is on an org citation or citation-reference, embark with allow us to directly call the relevant functions in the same way.

Do you mean (add-to-list 'embark-keymap-alist '(bibtex . bibtex-actions-map))? Functions in bibtex-actions-map can be called via embark-act when you are using bibtex-actions-at-point or other commands.

[bdarcus]

Here's an example to use embark to open links:

Just curious, but in that example, couldn't you just use higher level org-element stuff to identify link (and other org) objects, and tell embark about it?

Functions in bibtex-actions-map can be called via embark-act when you are using bibtex-actions-at-point or other commands.

Ok. Seems we ought to open a branch to figure out what code and documentation we need for this.