emacs-citar/citar

Emacs package to quickly find and act on bibliographic references, and edit org, markdown, and latex academic documents.

citar's Issues

Downcase all command names

bibtex-completion has one command that has "PDF". For consistency let's downcase the names?

format-entry widths

#66 fixed one problem, but introduced another minor one.

The default suffix template has ${tags:*}, which should extend the last column to the end.

But it's truncated much earlier (if you see below, it seems like the tags are truncated at about 27 characters).

Must be because we no longer assume a single template.

Here's what I see in ielm:

ELISP> (bibtex-actions--process-display-formats bibtex-actions-template-suffix)
((t "          ${=key=:15}    ${=type=:12}    ${tags:*}" . 45))
ELISP> bibtex-completion-display-formats-internal
((t "${author:36} ${title:*} ${year:4} ${=has-pdf=:1}${=has-note=:1} ${=type=:7}" . 53))

drop Emacs 26.3?

This is a new package without wide usage ATM. And Ubuntu's next release in a few weeks will.move to 27.1.

Thoughts?

CRM wrapper?

I'm not sure this will ever be needed, but I'll just note it for now.

In this comment, minad recommends the following:

I would recommend everyone to write a small wrapper around completing-read, simply because the completing-read API is so ugly. Like I did with consult--read. But in most cases a much simpler wrapper will do.

This might be worth pursuing if at some point we need that function to do more than it does now.

To be clear, we already do have a wrapper; I just mean a more configurable one.

add suffix UI

To accompany the recent prefix addition, add a configurable suffix.

add bibtex-actions--format-candidate

Need to fix a bug with #77, but while I'm at it, should move most of that function to separate one for individual candidates.

Generalize bibtex-actions-get-key-org-cite

The bibtex-actions-get-key-org-cite at-point function currently only works on citation-reference objects and so only on a single key.

It should be enhanced to also work on citation objects and multiple-keys.

Note, though: the initial-value would need to be set to a regex of the multiple keys, while the org-cite follow processor (see #141) would need to a pass a list of keys to the called function.

This does lead to me wonder if #141 might better be decoupled from bibtex-actions-at-point.

See org-cite-basic-goto for an example:

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

EDIT: Nicolas just now added a "key-only" optional argument to org-cite-get-references, which should allow this @ilupin:

(bibtex-actions-default-action (org-cite-get-references citation keys-only))

Support csl-json

Joost merged the parsebib wip/csl branch, which gives support for direct parsing of both bib and json files.

ELISP> (defvar my/bibtest (parsebib-parse (org-cite-list-bibliography-files)))
my/bibtest
ELISP> (gethash "low2001" my/bibtest)
(("subtitle" . "gated communities and the discourse of urban fear")
 ("title" . "The Edge and the Center")
 ("number" . "1")
 ("langid" . "english")
 ("urldate" . "2016-02-18")
 ("doi" . "10.1525/aa.2001.103.1.45")
 ("issn" . "1548-1433")
 ("pages" . "45--58")
 ("volume" . "103")
 ("journaltitle" . "American Anthropologist")
 ("date" . "2001-03-01")
 ("author" . "Low, Setha M.")
 ("shorttitle" . "The Edge and the Center")
 ("=type=" . "article")
 ("=key=" . "low2001"))

Just need a function something like this to manage field name mappings.

(defvar bibtex-actions-field-map
  '(("date" "year" "issued")
    ("author" "editor")
    ("booktitle" "container-title")))

(defun bibtex-actions-get-value (item field)
  "Return biblatex FIELD value for ITEM."
  (or (cdr (assoc-string field item 'case-fold))
      (catch 'success
        (dolist (fm (cdr (assoc field bibtex-actions-field-map)))
          (when fm
            (throw 'success (cdr (assoc-string fm item 'case-fold))))))))

Would also allow removing the bibtex-completion dependency for parsing and such.

This approach would suggest:

1. maybe a new bibtex-actions-bibliography variable to hold the list of bib (bibtex and/or csl-json) files to load
2. maybe a new bibtex-actions-init function to load them etc
3. replace current bibtex-completion-get-value calls with parsebib-get-value, or bibtex-actions-get-value

Note the new parsebib-parse function also does error handling.

Major caveat some bibtex-completion functions currently depend on it's parsing code, though I need to figure out which ones, and how. Also, it might be worth postponing this to see what happens with affixation/decoration in Emacs 28.

joostkremers/parsebib#12

add watch functions/commands?

Not sure about this, but we could add a convenience function/command to add and remove file-notify watches?

I wouldn't want to have any hard-coded assumptions though.

For sake of possible illustration, maybe something like:

(bibtex-actions-add-watch)
(bibtex-actions-rm-watch)

... and an accompanying defcustom?

(setq bibtex-actions-watch (list bibtex-completion-bibliography bibtex-completion-notes-path))

Or alternately, we can out some of this on the wiki.

cc @wenjie2wang

Should one or both core read functions be public?

Right now, we have:

• bibtex-actions--read
• bibtex-actions--completing-read

I figure I may as well ask the question now: should we make one or both of them public, and so:

• bibtex-actions-read
• bibtex-actions-completing-read

EDIT: The linked PR makes the first public, but prompts me to wonder whether it even makes sense to have the two functions. I settled on this split for the bibtex-completion PR, but not sure it's needed here.

Please add autoloads

First of all, thanks for a great package! It completes my migration to selectrum and allows me to finally remove helm.

When loading the package via use-package, I had to add a special section for predefining the interactive command:

(use-package bibtex-actions
  :quelpa (bibtex-actions)
  :commands (bibtex-actions-open-notes) ;; that one enables lazy loading
  :bind
  (("C-x l" . bibtex-actions-open-notes)))

So I guess if you'd just add an autoload cookie to the interactive entry points, there'd be no need for the :commands part here.

allow bibtex-actions-read to accept optional files parameter

I see no reason not to do this, and will give additional flexibility.

OTOH, there doesn't appear to be an obvious need right now. Maybe best to wait for a specific request or PR?

Add run script to tests

Adapt one of the selectrum test scripts to bibtex-actions, and add to the test dir.

Action does not work

Hi, thanks for the package.

I found that actions in bibtex-actions-open do not work. Below is my setup.

;; -- lexical-binding: t; --

(setq straight-use-package-by-default t
straight-check-for-modifications nil
straight-vc-git-default-clone-depth 1)

;; straight.el
(defvar bootstrap-version)
(let ((bootstrap-file
(expand-file-name "straight/repos/straight.el/bootstrap.el" user-emacs-directory))
(bootstrap-version 5))
(unless (file-exists-p bootstrap-file)
(with-current-buffer
(url-retrieve-synchronously
"https://raw.githubusercontent.com/raxod502/straight.el/develop/install.el"
'silent 'inhibit-cookies)
(goto-char (point-max))
(eval-print-last-sexp)))
(load bootstrap-file nil 'nomessage))

(defun straight-update-all ()
(interactive)
(straight-pull-all)
(straight-rebuild-all))

(setq use-package-verbose nil
use-package-enable-imenu-support t
use-package-always-defer t)
(straight-use-package 'use-package)

(defvar bibtex-base "~/org/bibliography/")
(defvar bibtex-pdf-directory (expand-file-name "pdf/" bibtex-base))
(defvar bibtex-note-directory (expand-file-name "papers/" bibtex-base))
(defvar bibtex-bibliography-list `(,(expand-file-name "references.bib" bibtex-base)))

(use-package bibtex-completion
:init
(use-package biblio
:bind (:map biblio-selection-mode-map
("n" . biblio--selection-next)
("p" . biblio--selection-previous))
:init (setq biblio-download-directory bibtex-pdf-directory))

(setq bibtex-completion-cite-prompt-for-optional-arguments nil
bibtex-completion-bibliography bibtex-bibliography-list
bibtex-completion-library-path bibtex-pdf-directory
bibtex-completion-notes-path bibtex-note-directory
bibtex-completion-display-formats '((t . "${year:4}\t${author:28}\t${title:*}"))
bibtex-completion-pdf-open-function #'bibtex-completion-pdf-open-external)

(with-eval-after-load 'org-ref-helm-bibtex
(setq bibtex-completion-display-formats '((t . "${year:4}\t${author:28}\t${title:*}"))))

:config
(defun bibtex-completion-pdf-open-external (file)
(save-window-excursion
(async-shell-command
(format "open %s" (shell-quote-argument file))))))

(use-package bibtex-actions
:straight (:host github :repo "bdarcus/bibtex-actions")
:demand t
:after (:any org latex)
:config
(setf (alist-get 'bibtex embark-keymap-alist) 'bibtex-actions-map)
(with-eval-after-load 'org-ref
(define-key org-mode-map [remap org-ref-insert-link] #'bibtex-actions-insert-key)))

(use-package selectrum
:hook (after-init . selectrum-mode)
:bind (("C-x C-z" . selectrum-repeat))
:init (setq selectrum-max-window-height 7))

(use-package prescient
:hook ((after-init . prescient-persist-mode))
:init
(use-package company-prescient
:hook (global-company-mode . company-prescient-mode))

(use-package selectrum-prescient
:hook (selectrum-mode . selectrum-prescient-mode)))

(use-package consult
:demand t
:after selectrum
:bind (("M-"" . consult-complex-command)
("C-x b" . consult-buffer)
("C-x 4 b" . consult-buffer-other-window)
("C-x 5 b" . consult-buffer-other-frame)
("C-x r j" . consult-register)
("C-x r l" . consult-bookmark)
("C-s" . consult-line)
("C-c a" . consult-git-grep)
("C-c i" . consult-imenu)
("C-c I" . consult-project-imenu)
("M-y" . consult-yank-pop)
("M-g m" . consult-mark)
("M-g k" . consult-global-mark)
("M-g o" . consult-outline)
("M-g f" . consult-find)
("M-g e" . consult-error)
("M-s m" . consult-multi-occur)
(" a" . consult-apropos))

:init
(setq consult-async-min-input 1
consult-ripgrep-command "rg --null --line-buffered --color=ansi --max-columns=1000 --no-heading --line-number . -e ARG OPTS")

(setq consult-preview-key nil
consult-config '((consult-line :preview-key any)))

(setq xref-show-xrefs-function #'consult-xref
xref-show-definitions-function #'consult-xref))

(use-package embark
:demand t
:after consult
:bind (("C-z" . embark-act)))

(use-package embark-consult
:demand t
:after (embark consult)
:hook (embark-collect-mode . embark-consult-preview-minor-mode))

When I call embark-act (C-z in my case) and e which should call bibtex-actions-open-notes, nothing happens and minibuffer exits. A message is printed at the same time: Done (re)loading bibliography. [2 times]

However, when I call bibtex-actions-open-notes directly and press Enter, it works fine.

The problem happens when using other actions too.

All package are using the latest master version on github.

add ability to filter on presence of PDFs, notes, links

To enhance the UX, when coupled with the corresponding symbols or icons in #33.

I also requested this for bibtex-completion, as it seems a simple and generally-useful enhancement: tmalsburg/helm-bibtex#363.

add a script for development testing

The new run.sh script is for users to test the released MELPA version.

I'd personally like an analog for development testing, which instead of installing bibtex-actions from MELPA, loads the local version.

bug: macro "or" statement on "name" variable not working consistently

Two possibilities:

1. something weird with my installation, and this code is fine
2. something wrong with this code

I'd like to establish which it is, and if 2, fix it.

166e9c9

Preparing for 1.0; last call for command or function name changes

@apc raised a question about the wisdom of the bibtex-actions-open command name, and I explained the reasoning in a followup here: #120 (comment).

I'm kind of agnostic, so would probably leave as is unless there were strong arguments in favor of changing.

But now is the time to raise the question, as I'm planning to tag 1.0 soon, which is me arbitrarily drawing a line-in-the-sand on command and function name changes.

It doesn't mean we can't revisit later, but that I'd prefer not to.

To recap, we have the follow action verbs:

1. open
2. insert
3. add

... and then command names based on these, the potential confusing ones being:

• bibtex-actions-open
• bibtex-actions-open-entry

Do note that aside from the clarity of the commands, I was also shooting for conciseness, to accommodate M-x, and menu displays like which-key (though see [this comment]((defalias 'apc/bib-open #'bibtex-actions-open-entry))) when using embark-act.

Bottomline, this (with marginalia annotations from the docstrings) should be as elegant, clear and concise as possible:

So what do people think?

cc @mtreca @wenjie2wang

Ensure crm-separator is set for bibtex-actions--completing-read

This code won't run correclty unless the crm-separator variable is reset from default when the completing-read function runs.

The code does not ATM ensure this.

How to fix?

bibtex-actions-read returns (nil nil) when selecting item

I have encountered a strange bug: Certain bibliography items seem to cause bibtex-actions-read to hickup. It returns (nil nil). Here's the .bib file:

@book{jorke_2003_Demokratie,
  title = {Demokratie als Erfahrung: John Dewey und die politische Philosophie der Gegenwart},
  shorttitle = {Demokratie als Erfahrung},
  author = {Jörke, Dirk},
  date = {2003},
  publisher = {{Westdt. Verl}},
  location = {{Wiesbaden}},
  url = {http://bvbr.bib-bvb.de:8991/F?func=service&doc_library=BVB01&doc_number=010344150&line_number=0001&func_code=DB_RECORDS&service_type=MEDIA},
  urldate = {2012-08-31},
  file = {/home/jv/Zotero/storage/3LUESP9S/Jörke - 2003 - Demokratie als Erfahrung John Dewey und die polit.pdf},
  langid = {german}
}

@article{joerissenAnthropologischeHinsichtenPragmatische2002,
  title = {Anthropologische Hinsichten, pragmatische Absichten},
  author = {Jörissen, Benjamin},
  date = {2002},
  pages = {24},
  file = {/home/jv/Zotero/storage/X7X3JUAD/Jörissen - 2002 - Anthropologische Hinsichten, pragmatische Absichte.pdf},
  langid = {german}
}

Selecting the first item yields the key (in a list); selecting the second item yields (nil nil).

Trying to debug that behavior, I encountered another weird error. I wanted to instrument the function with edebug. Edebug, however, said the defun was malformed. So I added a fake variable to the argument list:

(cl-defun bibtex-actions-read (&optional _fake_argument &key initial rebuild-cache)
  "Read bibtex-completion entries. ....")

Now debugging worked -- but the error was gone!

So it turned out that the error occurs only as long as I use the byte compiled version of the package. If I evaluate the function in the buffer directly, everything works fine. I get the error again if I explicitly force a reloading of the package with (load "bibtex-actions").

So my guess is that the problem has to do with compilation.

I use GNU Emacs 27.2 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.27, cairo version 1.17.4) of 2021-03-26, and the latest bibtex-actions commit 149f9ae.

No selection highlighting

As mentioned in #45, selectrum's syntax highlighting is not shown when using bibtex-action functions. Looking at the README, there doesn't seem to be any highlighting either (except an current line background highlight).

I originally thought that changing bibtex-completion-display-formats was responsible (through bibtex-actions-rich-ui), but setting it to nil doesn't change anything.

The other major change from my implementation (which still displays faces properly) is the use of propertize in bibtex-actions-get-candidates, which I suspect resets pre-existing face settings in the completion minibuffer.

Add predefined searches

Along with #118, we could support arbitrary pre-defined searches also, as supported in ivy-bibtex and helm-bibtex.

https://github.com/tmalsburg/helm-bibtex#predefined-searches

How best to do this here, given we have no common entry point command?

We might need a generic bibtex-actions command that can be wrapped like this; so:

(defun my/bib-mypubs ()
   (bibtex-actions :initial "Doe"))

... or simply tell users to wrap their default action command.

But if we did this, I guess I'd need an optional initial parameter on all commands.

Any other ideas?

Though I've tried to avoid macros, maybe this would be a good candidate?

OTOH, I'm not clear how useful this feature is, given how easy it is to run a search. The example of searching for your own pubs is not a very compelling one in my view.

Maybe could be useful for things like project-related searches though?

face conflict in README instructions with mouse highlight

Do you have any idea why the face properties specified as in the all-the-icons setup from the README are being overridden by selectrum-mouse-highlight?

Perhaps it'd be best to explain the odd behavior I'm encountering. Using the values for bibtex-actions-symbols from that snippet in the README, I get (as expected) that the pdf icon (e.g.) for an entry without a corresponding pdf is displayed in the face bibtex-actions-icon-dim. If, however, my mouse happens to be hovering over that entry, the icon is displayed using (I think?) the default face:

Without the pesky mouse hovering over anything:

With the mouse:

Originally posted by @apc in #94 (comment)

Add support for new org cite

While it's not done or merged yet, this thread suggests it likely will be "soon" (the syntax is basically done, as is a draft API).

https://lists.gnu.org/archive/html/emacs-orgmode/2021-04/msg00430.html

When it is, citation insertion would need to be adapted to take advantage of it, ideally in bibtex-completion. I don't believe the bibtex-completion-insert-citation function even needs to be changed to do this, given it has customization capabilities; see:

https://github.com/tmalsburg/helm-bibtex#format-of-citations

#113 is adding this.

I'd expect there would be overlap with org-ref too.

It seems, however, there will be opportunities here too, regardless of what code ends up where.

See, for example, #91, which may we the place to start.

PRs welcome, as I'm not sure I have the time or skill to do this ATM.

Aside: this project is under more active current development than bibtex-completion et al. So at times it makes sense to add code here that might later be transferred over to the former later. We use the same license, so that won't be any impediment.

NOTE on issues vs discussions

FYI, I decided to setup the new GitHub "discussion" feature for discussions that have always had to happen in the issue tracker. If you have questions, general feedback, etc., take a look.

I also started a status thread (#31) over there.

Improve CRM UI

As noted in the README, support for multiple candidate selection isn't great.

I do think the ideal long-term solution is for completion UIs to implement something similar to the helm approach; to improve their CRM UIs.

But in the absence of that, I thought I'd point out this suggestion, which could be a reasonable shorter-term improvement, say for inclusion in the wiki.

minad/vertico#1 (comment)

The basic idea is to have a "short" representation of the candidate string that would be used in the CRM prompt.

Could also be useful for #91.

Sort candidates by date-added

I'm not sure how practical this is, given it would need to depend on a date-added field in the data, but it makes sense from a UX perspective: to present the most recently added references first.

Simplify command names and docstrings

In line with the effort to streamline command names, should we change bibtex-actions-edit-notes to bibtex-actions-open-notes?

Perhaps the same question applies to "show-entry"?

That could simplify action verbs to "open" and "insert", for the most part.

FWIW, here's the helm-bibtex action descriptions. Maybe first line of the docstrings could also be shorter like this?

    :action (helm-make-actions
             "Open PDF, URL or DOI"       'helm-bibtex-open-any
             "Open URL or DOI in browser" 'helm-bibtex-open-url-or-doi
             "Insert citation"            'helm-bibtex-insert-citation
             "Insert reference"           'helm-bibtex-insert-reference
             "Insert BibTeX key"          'helm-bibtex-insert-key
             "Insert BibTeX entry"        'helm-bibtex-insert-bibtex
             "Attach PDF to email"        'helm-bibtex-add-PDF-attachment
             "Edit notes"                 'helm-bibtex-edit-notes
             "Show entry"                 'helm-bibtex-show-entry
             "Add PDF to library"         'helm-bibtex-add-pdf-to-library))

Add completion-at-point

Overview

Perhaps at-point completion would be more efficient for the more narrow task of citation and/or key insertion when writing, particularly for the forthcoming new org-mode citation support, something like you see in the Zettlr markdown editor?

Don't really know anything about this, but thought of it because of this new package.

https://github.com/minad/corfu

And there's, of course, company.

If the feature makes sense, I may experiment with it. But a PR would be even better!

EDIT: see this comment for limitations and possibilities, in particular the note you can make it possible move from at-point to the minibuffer.

Possible implementation approach

If I understand how the API works, we'd probably want something like the following functions:

Edited based on discussion in comments.

1. bibtex-actions-complete-key-at-point (as with Zettlr screenshot above; the easiest and most general, and will cover 90% or so of need, and work with both org and pandoc syntax)
2. bibtex-actions-complete-citation-at-point (specifically for new org cite support, which will have more complex syntax and features; see #108)

Org-cite syntax

Here's the new syntax:

 [cite/style:common prefix ;prefix @key suffix; ... ; common suffix]

Goal is to make citation entry really smooth and efficient, then.

So I'm thinking user experience would be something like:

• type [c and that can auto-complete to [cite
• type / and presents pop-up options of styles, completes that, and places point after this [cite/style:
• type @ and list of citation keys pops up for selection (this seems the only piece that would be necessary)
• etc.

Include default display-format better suited to wider range of data

I work closer to the humanities and use biblatex for the data format, and work with a sources that sometimes don't have authors or title, or which use alternate fields for year like date.

The result is I have lines in my display that are mostly empty.

Though we have to check whether anything's changed in bibtex-completion since I submitted it, see tmalsburg/helm-bibtex#192, including proposed solution.

Maybe we should include that so display works better out-of-box out-of-box?

Or maybe better, move example configurations to the wiki?

Can we have descriptions on the keybindings that show up in which-key menus

I couldn't figure if this is possible, and if so, how. Is this possible?

Do we even care?

Edit: no, and yes; see #57 and #143 (comment)

multi-select broke

Selection of multiple candidates broke (returns empty results), as a result of this change. I guess I didn't test it enough.

The first result below is with a single selection, and the other with two.

ELISP> (bibtex-actions-read)
("sassen2000")

ELISP> (bibtex-actions-read)
(nil nil)

I've established the problem is with --get-candidates.

field alignments with prefixes

from @apc

I've tried setting the value of bibtex-actions-template-suffix to include ${=has-pdf=:1}${=has-note=:1}:.

bibtex-actions-template-suffix is a variable defined in ‘bibtex-actions.el’.
Its value is
((t . "          ${=key=:15} ${=has-pdf=:1}${=has-note=:1}   ${=type=:12}    ${tags:*}"))
Original value was 
((t . "          ${=key=:15}    ${=type=:12}    ${tags:*}"))

  You can customize this variable.

Documentation:
Configures formatting for the BibTeX entry suffix.
When combined wiht the main template, the same string is used for
display and for search.

I've checked the value of bibtex-actions-template and it is what I assume it should be:

bibtex-actions-template is a variable defined in ‘bibtex-actions.el’.
Its value is ((t . "${author:20}   ${title:48}   ${year:4}"))

  You can customize this variable.

Documentation:
Configures formatting for the BibTeX entry.
When combined with the suffix, the same string is used for
display and for search.

I now see the symbols indicating presence of notes and/or pdfs. But somehow they appear twice and break the alignment of the entries:

Any advice on how to adjust this?

(Thanks again!)

I'm on Emacs 27.2.

Originally posted by @apc in #93

Add "bibtex-actions" org-cite "follow" processor

Once org-cite is merged to org-mode master ...

Edit: see comment from @ilupin #143 (comment) with example code to add to the package.

 (org-cite-register-processor 'bibtex-actions
    :follow (lambda (_ _) (call-interactively 'bibtex-actions-at-point)))

Just need to then add this to the README:

(setq org-cite-follow-processor 'bibtex-actions)

---

The org-cite author describes "follow" processors succinctly as "Follow is what happens when you use C-c C-o on a citation."

We can in turn use embark to attach additional commands, per @publicimageltd #137 (comment), for a lightweight emarkified org-ref-like experience.

The user would then have different choices for at-point functionality; they could do any mix of the following:

1. use bibtex-actions-at-point to open a bibtex-actions command filtered to key(s)
2. use org-open-at-point to run the bibtex-completion functions directly (this may be better than 1?)
3. with 2, also add additional functions, via a keymap, for access with embark-act (see #142)

The user would then do:

  (setq org-cite-follow-processor 'bibtex-actions)

See also #140, and org-cite-basic-goto for an example:

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

Seems like we might want to split the keymap and have a subset specific to at-point commands?

cc @ilupin and (since he might be curious) @oantolin

Add affixation function to support prefixes and suffixes for candidate display

See #28 (comment) and minad/marginalia#50 (comment).

Emacs 28 introduces affixation support, which we should be able to exploit for a more functional and elegant UI/UX.

To do that, we need an affixation function, or even a separate package, that adds color-differentiated note/pdf/link icons to the prefix where those items are associated with the candidate, and (maybe user-configurable) secondary metadata to suffix.

Has to be gorgeous, functional, and work well on dark and light themes.

The idea is this would enhance visual scanning of the candidate list (and, TBH, improve the aesthetics).

Example mockup:

This will address how to filter on these: tmalsburg/helm-bibtex#363.

Details

The bibtex-completion-candidates function includes the metadata one can use to construct the affixes, and I assume we want to use all-the-icons for the actual icons.

Resolution

I've merged the linked PR with configurable main display and suffix. The latter should also work for pre-Emacs 28 using the annotation-function I added, though I haven't tested this.

add key to "invisible" part of candidate to ensure uniqueness

This may be overthinking things, but the approach here now is that the candidate search string is configured with the two defcustoms. While there are sensible defaults there, it might be feasible that a user configures these in such a way that the candidates are not all unique. For example, say they nil the suffix, and some records don't have titles.

Potential simple solution: add the key to the "invisible" section of the candidate.

Support multiple candidate selection

In helm-bibtex, when presented with a list of candidates, one can do the following:

• hit control-space to mark multiple candidates
• hit tab to access action options, or return to run default

In my view, this is an almost ideal UX for selecting and acting on multiple candidates (though arguably the selected candidates should then be grouped at the top of the list).

That will then pass multiple keys to the relevant functions, and for the insert-at-point commands, those functions take care of the formatting; in some cases they are comma-separated inline, and in others (like inserting BibTeX entries), they are separated by newlines.

So how to do this here?

The obvious answer is to change the read function to use completing-read-multiple.

But the selectrum UI support for multiple selection is not really optimized for examples like this with very long candidates. Same for icomplete-vertical, which uses a similar UI.

I did, however, submit an enhancement request to selectrum to support this case. No code yet, but I'm optimistic we will see it.

So it would be good to resolve this on our end before this happens, so we can test and contribute feedback.

Seems we would also need to get embark to support multiple (see comment).

Make macro optional parameter required, or remove macro entirely

This commit introduced the option on the bibtex-actions-define-action macro to explicitly specify the command name, rather than to construct it from the bibtex-completion function names:

166e9c9

Perhaps we should remove the latter functionality, and just require explicitly defining the name?

But arguably that simplifies the macro enough that maybe it's not not needed at all? And there might be benefit in having explicit functions?

Edit: the linked PR does in fact remove the macro.

(defun bibtex-actions-open (keys)
  "doc"
  (interactive (list (bibtex-actions--read)))
  (bibtex-completion-open-any (list keys)))

UI options, add annotation function?

Right now, the UI presents a single, undifferentiated, formatted propertized display string, but internally searches using a different string.

This works well, though does result in some problems with multiple candidate selection currently (see #17).

But there's room with completing-read to use annotations for secondary bits of supporting information. Affixation (recently added to Emacs 28) obviously fits here too, though am unclear on the connection between them.

Is there value in rethinking the UI a bit to take advantage of that, and adding an annotation and/or affixation function to support it, either here or in a separate package?

If yes, how would that look, and what should that function generate?

Perhaps prefixes with nice icon fonts to indicate presence of pdfs, notes, or links?

Maybe a suffix with the key, type, and maybe tags?

If yes, the actually displayed string would be more compact (say just author, date, title?) to make room.

Something like this, with blue box indicating main display, and yellow affixes:

Maybe it's user-configurable?

Also, early in these discussions, @minad suggested the possibility of a separate package for annotation.

I suppose this ultimately depends just how rich these annotation/affix-based UIs can be now; what improvement they might offer.

Ideally, though, it would simultaneously enhance both the default orientation towards selectrum completion, while also opening up other opportunities.

Or we just don't worry about it for now; it's easy enough to add later, and it might be wise to allow these features to mature in Emacs

If someone does want to experiment with this, and believes to have come up with a better UI, do post screenshots.

See also #20.

add caching of bib candidates

Thanks for this nice package! I gave it a try and it worked smoothly for me.

I have a relatively large BibTeX file with over 1,000 entries (and 10,000 lines) and I have been using ivy-bibtex. The bibtex-ctions takes a noticeable time to read/load the BibTeX file every time, while ivy-bibtex takes a noticeable time only the first time (assuming that the BibTeX file has not been changed). I guess it is because ivy-bibtex somehow caches the BibTeX file that has been read the first time. Thus, IMHO, it would be great if bibtex-actions contains a similar caching mechanism.

Originally posted by @wenjie2wang in #68

test: update test.bib to better test UI

Given we now have a nice testing script, seems like we should revise the test.bib file etc to better test out the UI; things like:

• tags
• PDFs/notes

candidate multi-select broken (again)

I really need to remember to test this before merging changes ...

Latest commit break things again.

I'm assuming I need to trim a string somewhere.

Differences between this and helm-bibtex and ivy-bibtex

For possible documentation:

• like helm-bibtex, but unlike ivy-bibtex, bibtex-actions has support for multi-selection of candidates (conditioned on resolving #17)
• helm-bibtex and ivy-bibtex provide a single command, and the actions accessed from there; bibtex-actions provides all of its actions as standard commands, available from M-x, without a single entry point.
• bibtex-actions is based on completing-read-multiple, with a single dependency, and works with different completion systems (though in practice is best supported in selectrum) and supporting packages that are completing-read compliant; helm-bibtex and ivy-bibtex are based on helm and ivy respectively

keep UI updated when changes to bib file(s) and pdf/note availability

Here's what we want:

If a user modifies specified bib files or note or pdf directory, the UI should update; e.g. the bibtex-actions-refresh command should auto-run.

I couldn't figure out how to elegantly add this (I don't want to use the bibtex-completion approach to this), but see this wiki section for some ideas.

https://github.com/bdarcus/bibtex-actions/wiki/Configuration#proactive-reloading-of-library

I think ideally a user could add a "watcher" function to their config, and have it handle this seemlessly, but that it would not be on by default.

It might even be a separate file, as with straight.

A PR is welcome.

tmalsburg/helm-bibtex#369

minor-mode?

Would this make sense @mohkale?

if we want to do this ...

I wish github had messaging. @mtreca - I added you to this repo just in case we wanted to do this apart from helm-bibtex. While there are downsides, there are also advantages.

Only makes sense, though, if the changes aren't added to bibtex completion (which I much prefer), so we should wait on that decision.

If we do go this direction, you could add your code, and I could add my changes on top of it.

MELPA

I think this code is solid, and the elisp-check github action I've been using from the beginning is passing fine.

If you're using this package without issue and support submitting it, however, please weigh in here, with a thumb's up on this post, or any specific comments?

The file will just be:

(bibtex-actions :repo "bdarcus/bibtex-actions"
  :fetcher github)

Make initial value for the different actions customizable

While debugging that crm problem, I encountered a more conceptual issue. Vanilla Emacs has no sophisticated completion system, it just offers you all strings which match the inital input from the beginning on (like "^initial input). Therefore, the initial input (like "has:pdf") will not filter the list of available items. I had to delete the initial input in order to access the item. It only works if you have the appropriate completion style installed, in my case, that would be orderless. Assuming that one goal of that package is to provide completion with as little requirements as possible, it makes sense to remove that functional dependency.

So my suggestion is to introduce a variable to make the initial input customizable. Here's a draft:

(defcustom bibtex-actions-initial-inputs 
  '((files . "has:pdf")
    (notes . "has:notes")
 ...)

(defcustom bibtex-actions-filter-with-initial-input t
  "Set this to nil of you use an 'unflexible' completion style"
....)

(defun bibtex-actions--get-initial-input (input-type)
 (when bibtex-actions-filter-with-initial-input
  (assoc input-type bibtex-actions-initial-input))

(defun bibtex-actions-open-notes (keys)
    (interactive (list (bibtex-actions-read :initial (bibtex-actions--get-initial-input 'notes)
                                                              :rebuild-cache current-prefix-arg)))
   (bibtex-completion-edit-notes keys))

There would be further stuff to change, like bibtex-actions--affixation. And if we go that route, :initial could actually be changed to just pass a symbol, that would make the code more elegant.

What do you think?

Should I be seeing a list of available actions when calling `embark-act`?

Ivy user here, testing the waters. Thanks for setting this up. Had shied away from trying non-ivy packages because ivy-bibtex is a central part of my workflow.

I've now disabled all my ivy-related packages and setup selectrum, embark, consult, and bibtex-actions. If I try e.g. bibtex-actions-open I get a list of entries in my main bibliography file. But calling embark-act on any of them doesn't show me a list of options, which is what I would have expected. I see that typing e.g. o will open the URL associated with a given entry, but looking at the bibtex-actions-keymap doesn't help me figure out how to e.g. edit the associated note etc.

Sorry if I'm missing something obvious here!

EDIT: OK, I figured out where to get the values of bibtex-actions-keymap in a readable form. (I just needed to go to the source!). For reasons that escape me, calling C-h v on bibtex-actions-keymap shows me the following unhelpful list of values:

bibtex-actions-map is a variable defined in ‘bibtex-actions.el’.
Its value is shown below.

  This variable may be risky if used as a file-local variable.

Documentation:
Keymap for ’bibtex-actions’.

Value:
(keymap
 (97 . bibtex-actions-add-pdf-to-library)
 (101 . bibtex-actions-open-entry)
 (110 . bibtex-actions-open-notes)
 (116 . bibtex-actions-add-pdf-attachment)
 (98 . bibtex-actions-insert-bibtex)
 (107 . bibtex-actions-insert-key)
 (114 . bibtex-actions-insert-reference)
 (99 . bibtex-actions-insert-citation)
 (108 . bibtex-actions-open-link)
 (112 . bibtex-actions-open-pdf)
 (111 . bibtex-actions-open))

[back]

I was unaware that looking at bibtex-actions.el in this case would have shown a human readable value.

I still want to know whether I should be seeing a list of available actions when calling embark-act, and if not whether there's a way of having that show up. I realize this may be something having to do with my embark settings; if so, please just let me know and I'll close this. (I just copied the example settings from the README on the embark repository.)

Correct completion category?

Currently the code uses simply "bibtex".

But in this post , the author notes emacs has two internal bibtex-related categories:

• bibtex-key
• bibtex-string

Does it even matter for this purpose?