Skip to content

Commit

Permalink
docs (readme): change format to ospl (#117)
Browse files Browse the repository at this point in the history 
To make it easier to track diffs going forward, this converts the 
README to use "one sentence per line" formatting.
  • Loading branch information
@bdarcus
bdarcus authored Apr 28, 2021
1 parent 856da23 commit 743f548
Showing 1 changed file with 50 additions and 113 deletions.
163 changes: 50 additions & 113 deletions README.org
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,15 +17,10 @@
:CUSTOM_ID: what-is-it
:END:

This package turns bibtex-completion functions into
completing-read-based Emacs commands. When used with selectrum, embark,
and marginalia, it provides similar functionality to helm-bibtex and
ivy-bibtex: quick filtering and selecting of bibliographic entries from
the minibuffer, and the option to run different commands against them.
This package turns bibtex-completion functions into completing-read-based Emacs commands.
When used with selectrum, embark, and marginalia, it provides similar functionality to helm-bibtex and ivy-bibtex: quick filtering and selecting of bibliographic entries from the minibuffer, and the option to run different commands against them.

Here's a screenshot with
[[https://github.com/raxod502/selectrum][selectrum]] and
[[https://github.com/oantolin/embark/][embark]].
Here's a screenshot with [[https://github.com/raxod502/selectrum][selectrum]] and [[https://github.com/oantolin/embark/][embark]].

#+CAPTION: selectrum-embark screenshot
[[file:images/selectrum-embark.png]]
Expand All @@ -40,8 +35,7 @@ And another with [[https://github.com/minad/vertico][vertico]]:
:CUSTOM_ID: installation
:END:

Bibtex-actions is available for installation from
[[https://melpa.org][MELPA]].
Bibtex-actions is available for installation from [[https://melpa.org][MELPA]].

** Configuration
:PROPERTIES:
Expand All @@ -62,13 +56,9 @@ To setup bibtex-actions using =use-package=, you can simply do:
(add-to-list 'embark-keymap-alist '(bibtex . bibtex-actions-map)))
#+END_SRC

Since most of the command logic resides in bibtex-completion, that is
where to look for different
[[https://github.com/tmalsburg/helm-bibtex#basic-configuration-recommended][configuration
options]].
Since most of the command logic resides in bibtex-completion, that is where to look for different [[https://github.com/tmalsburg/helm-bibtex#basic-configuration-recommended][configuration options]].

The only thing, however, that you /must/ configure is where to find your
bib file(s).
The only thing, however, that you /must/ configure is where to find your bib file(s).

#+BEGIN_SRC emacs-lisp
(setq bibtex-completion-bibliography "~/bib/references.bib")
Expand All @@ -78,31 +68,22 @@ bib file(s).
:PROPERTIES:
:CUSTOM_ID: completion-styles
:END:

One of the beauties of the new suite of completing-read packages is the
flexibility. You can read more about this at the
[[https://github.com/raxod502/selectrum#usage][selectrum README]], but
here's an example using orderless with its
[[https://github.com/oantolin/orderless#style-dispatchers][style
dispatchers]].
One of the beauties of the new suite of completing-read packages is the flexibility.
You can read more about this at the [[https://github.com/raxod502/selectrum#usage][selectrum README]], but here's an example using orderless with its [[https://github.com/oantolin/orderless#style-dispatchers][style dispatchers]].

#+CAPTION: orderless matching
[[file:images/orderless.png]]

In this case, that search string is searching for all items without
either a PDF or note associated with them, and then includes a "the"
initialism, and a flex search on "abc".
In this case, that search string is searching for all items without either a PDF or note associated with them, and then includes a "the" initialism, and a flex search on "abc".

*** Test Script
:PROPERTIES:
:CUSTOM_ID: test-script
:END:

The repository =test= directory also includes a script you can use to
run this and associated packages in the =emacs -Q= sandbox. To do that,
simply run =./run.sh= from the =test= directory. By default, this will
use selectrum as the completion system. If you would like to try vertico
instead, just do =M-x vertico-mode=.
The repository =test= directory also includes a script you can use to run this and associated packages in the =emacs -Q= sandbox.
To do that, simply run =./run.sh= from the =test= directory.
By default, this will use selectrum as the completion system.
If you would like to try vertico instead, just do =M-x vertico-mode=.

*** Rich UI
:PROPERTIES:
Expand All @@ -111,35 +92,27 @@ instead, just do =M-x vertico-mode=.

There are three sections of the browsing UI.

1. The prefix, exploiting the affixation feature only available starting
with Emacs 28, and holding the symbols to indicate the presence of
PDFs or notes associated with the entries.
1. The prefix, exploiting the affixation feature only available starting with Emacs 28, and holding the symbols to indicate the presence of PDFs or notes associated with the entries.
2. The main display, which by default shows author, title, and date.
3. The suffix, which by default shows citekey, reference type, and (if
present) tags or keywords.
3. The suffix, which by default shows citekey, reference type, and (if present) tags or keywords.

You can search against all of the above content. For the prefix, you can
filter for associated PDFs or notes using =has:pdf= or =has:note=
respectively (and at least with my setup, even the =:p= or =:n=
shorthand).
You can search against all of the above content.
For the prefix, you can filter for associated PDFs or notes using =has:pdf= or =has:note= respectively (and at least with my setup, even the =:p= or =:n= shorthand).

#+CAPTION: UI sections
[[file:images/ui-segments.png]]

You can configure both of the last two just as you do with
bibtex-completion.
You can configure both of the last two just as you do with bibtex-completion.

#+BEGIN_SRC emacs-lisp
(setq bibtex-actions-template '((t . " ${title:*}")))
(setq bibtex-actions-template-suffix '((t . " ${=key=:15}")))
#+END_SRC

Note: the asterisk signals to the formatter to use available space for
the column. You should only use this on one field total, across the two
templates, for the formatting to work correctly.
Note: the asterisk signals to the formatter to use available space for the column.
You should only use this on one field total, across the two templates, for the formatting to work correctly.

By default, this UI is plain text, but you can configure it to use icons
instead.
By default, this UI is plain text, but you can configure it to use icons instead.

#+CAPTION: rich UI with icons screenshot
[[file:images/rich-ui-icons.png]]
Expand Down Expand Up @@ -168,14 +141,12 @@ Here's how to configure it to use =all-the-icons=:
:CUSTOM_ID: proactive-reloading-of-library
:END:

Bibtex-actions uses a cache to speed up library display. This is great
for performance, but means the data can become stale if you modify it.
Bibtex-actions uses a cache to speed up library display.
This is great for performance, but means the data can become stale if you modify it.

The =bibtex-actions-refresh= command will reload the cache, and you can
call this manually.
The =bibtex-actions-refresh= command will reload the cache, and you can call this manually.

You can also add =bibtex-completion=-style proactive loading by using
=filenotify= something like this:
You can also add =bibtex-completion=-style proactive loading by using =filenotify= something like this:

#+BEGIN_SRC emacs-lisp
;; Of course, you could also use `bibtex-completion-bibliography` here, but would need
Expand All @@ -184,8 +155,7 @@ You can also add =bibtex-completion=-style proactive loading by using
"/path/to/file.bib" '(change) 'bibtex-actions-refresh)
#+END_SRC

You can also extend this to do the same thing for your PDF files, or
notes:
You can also extend this to do the same thing for your PDF files, or notes:

#+BEGIN_SRC emacs-lisp
(file-notify-add-watch
Expand All @@ -195,9 +165,7 @@ notes:
bibtex-completion-note-path '(change) 'bibtex-actions-refresh)
#+END_SRC

For additional configuration options on this, see
[[https://github.com/bdarcus/bibtex-actions/wiki/Configuration#automating-path-watches][the
wiki]].
For additional configuration options on this, see [[https://github.com/bdarcus/bibtex-actions/wiki/Configuration#automating-path-watches][the wiki]].

** Usage
:PROPERTIES:
Expand All @@ -211,9 +179,8 @@ You have a few different ways to interact with these commands.
:CUSTOM_ID: m-x
:END:

Simply do =M-x= and select the command that you want, enter the terms to
find the item you are looking for, and hit return. This runs the default
action: the command you invoked.
Simply do =M-x= and select the command that you want, enter the terms to find the item you are looking for, and hit return.
This runs the default action: the command you invoked.

Here's the view, using marginalia for annotations.

Expand All @@ -224,81 +191,51 @@ A note on multiple candidate selection:

These commands do allow you to select multiple items, with two caveats:

1. For this to work correctly, you /must/ use the ampersand (=&=) as
=crm-separator= to separate the candidates.
2. We use very long candidate strings, so if you use a completion system
that requires you to =TAB=-complete, the experience is
less-than-ideal.
1. For this to work correctly, you /must/ use the ampersand (=&=) as =crm-separator= to separate the candidates.
2. We use long candidate strings, so if you use a completion system that requires you to =TAB=-complete, the experience is less-than-ideal.

*** Access an alternate action via =embark-act=
:PROPERTIES:
:CUSTOM_ID: access-an-alternate-action-via-embark-act
:END:

If while browsing you instead would rather edit that record, and you
have embark installed and configured, this is where =embark-act= comes
in. Simply input the keybinding for =embark-act= (in my case =C-o=), and
select the alternate action.
If while browsing you instead would rather edit that record, and you have embark installed and configured, this is where =embark-act= comes in.
Simply input the keybinding for =embark-act= (in my case =C-o=), and select the alternate action.

*** Use =embark-collect-snapshot=
:PROPERTIES:
:CUSTOM_ID: use-embark-collect-snapshot
:END:

A final option, that can be very useful: run =embark-collect-snapshot=
(=S=) from =embark-act=. This will select the candidate subset, and open
it in a separate buffer. From there, you can run the same options
discussed above using =embark-act= (which is also bound to =a= in the
collect buffer).
A final option, that can be useful: run =embark-collect-snapshot= (=S=) from =embark-act=.
This will select the candidate subset, and open it in a separate buffer.
From there, you can run the same options discussed above using =embark-act= (which is also bound to =a= in the collect buffer).

So, for example, say you are working on a paper. You hold the complete
superset of items you are interested in citing at some point in that
buffer. From there, you can run different actions on the candidates at
will, rather than search individually for each item you want to cite.
So, for example, say you are working on a paper. You hold the complete super-set of items you are interested in citing at some point in that buffer.
From there, you can run different actions on the candidates at will, rather than search individually for each item you want to cite.

** Comparisons
:PROPERTIES:
:CUSTOM_ID: comparisons
:END:

=Bibtex-actions= is inspired by =helm-bibtex= and =ivy-bibtex=, and uses
the same =bibtex-completion= backend, and so has the same basic capabilities.
This is inspired by =helm-bibtex= and =ivy-bibtex=, but is based on =completing-read=.
In comparison:

- like =helm-bibtex=, but unlike =ivy-bibtex=, =bibtex-actions= has
support for multi-selection of candidates
- =helm-bibtex= and =ivy-bibtex= provide a single command, and the
actions are accessed from there; =bibtex-actions= provides all of its
actions as standard commands, available from =M-x=, without a single

- like =helm-bibtex=, but unlike =ivy-bibtex=, =bibtex-actions= has support for multi-selection of candidates
- =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=, 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
- =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.

** Acknowledgements
:PROPERTIES:
:CUSTOM_ID: acknowledgements
:END:

The ideas in this project were initially worked out in a
[[https://github.com/tmalsburg/helm-bibtex/issues/353][conversation]]
with [[https://github.com/mtreca][Maxime Tréca]] and
[[https://github.com/minad][Daniel Mendler]]. Daniel, author of
[[https://github.com/minad/consult][consult]] and
[[https://github.com/minad/marginalia][marginalia]], helped us
understand the possibilties of the new suite of completing-read
packages, while Maxime came up with an
[[https://github.com/tmalsburg/helm-bibtex/pull/355][initial
prototype]].

This code takes those ideas and reimplements them to fill out the
feature set, and also optimize the code clarity and performance.

Along the way, [[https://github.com/clemera][Clemens Radermacher]] and
[[https://github.com/oantolin][Omar Antolín]] helped with some of the
intricacies of completing-read and elisp.

And, of course, thanks to [[https://github.com/tmalsburg][Titus von der
Malburg]] for creating and maintaining bibtex-completion and helm-bibtex
and ivy-bibtex.
The ideas in this project were initially worked out in a [[https://github.com/tmalsburg/helm-bibtex/issues/353][conversation]] with [[https://github.com/mtreca][Maxime Tréca]] and [[https://github.com/minad][Daniel Mendler]]. Daniel, author of [[https://github.com/minad/consult][consult]] and [[https://github.com/minad/marginalia][marginalia]], helped us understand the possibilities of the new suite of completing-read packages, while Maxime came up with an [[https://github.com/tmalsburg/helm-bibtex/pull/355][initial prototype]].

This code takes those ideas and re-implements them to fill out the feature set, and also optimize the code clarity and performance.

Along the way, [[https://github.com/clemera][Clemens Radermacher]] and [[https://github.com/oantolin][Omar Antolín]] helped with some of the intricacies of completing-read and elisp.

And, of course, thanks to [[https://github.com/tmalsburg][Titus von der Malburg]] for creating and maintaining bibtex-completion and helm-bibtex and ivy-bibtex.

0 comments on commit 743f548

Please sign in to comment.