helm-bibtex

#+TITLE: Bibtex-completion, helm-bibtex, ivy-bibtex #+Options: num:nil

Helm-bibtex: [[http://melpa.org/#/helm-bibtex][http://melpa.org/packages/helm-bibtex-badge.svg]] Ivy-bibtex: [[http://melpa.org/#/ivy-bibtex][http://melpa.org/packages/ivy-bibtex-badge.svg]]

Helm-bibtex and ivy-bibtex allow you to search and manage your BibTeX bibliography. They both share the same generic backend, bibtex-completion, but one uses the Helm completion framework and the other Ivy as a front-end.

News

2024-01-09: New customization variable ~~bibtex-completion-watch-bibliography~~. Can be used to deactivate automatic reloading of the bibliography.
2022-01-17: More support for org-mode citations, see [[https://github.com/tmalsburg/helm-bibtex#use-helm-bibtex-or-ivy-bibtex-as-an-org-cite-follow-processor][here]]. (Thanks to [[https://github.com/akirakyle][akirakyle]].)
2021-08-25: It is now possible to mark and act on multiple entries in ~~ivy-bitex~~. See [[#apply-actions-to-multiple-entries][here]].
2021-07-25: ~~helm-bibtex-with-local-bibliography~~ and ~~ivy-bibtex-with-local-bibliography~~ now also use locally and globally defined bibliographies in org files. These are bibliographies specified using the new ~~#+BIBLIOGRAPHY:~~ key word and those in the variable ~~org-cite-global-bibliography~~.
2021-07-18: Added a citation function for Org’s new citation system: ~~bibtex-completion-format-citation-org-cite~~ (for use in configuration variable ~~bibtex-completion-format-citation-functions~~)
2021-04-12: Added a section below explaining how the bibliography can be automatically reloaded when PDFs and notes are added. See [[https://github.com/tmalsburg/helm-bibtex#refresh-bibliography-when-new-pdfs-and-notes-are-added][here]].
2021-04-08: It is now possible to search for entries with PDFs and notes by entering ~~=has-pdf=~~ and ~~=has-note=~~.
2020-04-29: New commands ~~helm-bibtex-with-notes~~ and ~~ivy-bibtex-with-noted~~ for searching just within the entries that have notes.
2018-06-09: Added virtual APA field ~~author-or-editor~~ for use in notes templates.
2018-06-02: Reload bibliography proactively when bib files are changed.
2017-10-21: Added support for multiple PDFs or other file types. See sections “Additional PDFs” and “Other file types than PDF”.
2017-10-10: Added support for ~~@string~~ constants.
2017-10-02: Use date field if year is not defined.
2017-09-29: If there is a BibTeX entry, citation macro, or org-bibtex entry at point, the corresponding publication will be pre-selected in helm-bibtex and ivy-bibtex giving quick access to PDFs and other functions.

See [[file:NEWS.org]] for old news.

Key features

Quick access to your bibliography from within Emacs
Powerful search capabilities
Provides instant search results as you type
Tightly integrated with LaTeX authoring, emails, Org mode, etc.
Open the PDFs, URLs, or DOIs associated with an entry
Insert LaTeX cite commands, Ebib links, or Pandoc citations, BibTeX entries, or plain text references at point, attach PDFs to emails
Support for note taking
Quick access to online bibliographic databases such as Pubmed, arXiv, Google Scholar, Library of Congress, etc.
Import BibTeX entries from CrossRef and other sources.

Helm-bibtex’ and ivy-bibtex’ main selling points are efficient search in large bibliographies using powerful search expressions and tight integration into your Emacs workflows. They both can perform the following actions on entries matching the search expression: open the PDF associated with an entry, its URL or DOI, insert a citation for that entry, the BibTeX key, the BibTeX entry, or a plain text reference, attach the PDF to an email, take notes, edit the BibTeX entry. Many aspects can be configured to suit personal preferences.

Example

Below is a screenshot showing a helm-bibtex search for entries containing the expression “eye tracking”.

#+CAPTION: A search for publications containing the expression “eye tracking” [[file:screenshot.png]]

The regular expression ~~eye.?tracking~~ allows searching for different spellings (“eye tracking”, “eye-tracking”, “eyetracking”). A looped square symbol (⌘) next to an entry indicates that a PDF is available. A pen symbol (✎) means that there are notes attached to this entry. At the bottom, there are entries that can be used to search in online databases.

Installation

The easiest way to install helm-bibtex or ivy-bibtex is through [[http://melpa.org/#/helm-bibtex][MELPA]]. Alternatively, put the files [[file:bibtex-completion.el]] and either [[file:helm-bibtex.el]] or [[file:ivy-bibtex.el]] in a directory included in your load-path and add the following line to your start-up file (typically ~~init.el~~):

#+BEGIN_SRC emacs-lisp (autoload 'helm-bibtex "helm-bibtex" "" t) #+END_SRC

#+BEGIN_SRC emacs-lisp (autoload 'ivy-bibtex "ivy-bibtex" "" t) ;; ivy-bibtex requires ivy's ivy--regex-ignore-order regex builder, which ;; ignores the order of regexp tokens when searching for matching candidates. ;; Add something like this to your init file: (setq ivy-re-builders-alist '((ivy-bibtex . ivy--regex-ignore-order) (t . ivy--regex-plus))) #+END_SRC

Helm-bibtex and ivy-bibtex depend on a number of packages that will be automatically installed if you use MELPA.

When using helm-bibtex or ivy-bibtex, make sure that helm or ivy is correctly configured (see [[https://github.com/emacs-helm/helm#quick-install-from-git][helm documentation]] or [[http://oremacs.com/swiper/#installing-from-the-git-repository][ivy documentation]]).

Minimal configuration

A minimal configuration involves telling bibtex-completion where your bibliographies can be found:

#+BEGIN_SRC emacs-lisp (setq bibtex-completion-bibliography '("/path/to/bibtex-file-1.bib" "/path/to/bibtex-file-2.bib")) #+END_SRC

Org-bibtex users can also specify org-mode bibliography files, in which case it will be assumed that a BibTeX file exists with the same name and extension bib instead of org. If the bib file has a different name, use a cons cell ~~("orgfile.org" . “bibfile.bib")~~ instead:

#+BEGIN_SRC emacs-lisp (setq bibtex-completion-bibliography '("/path/to/bibtex-file-1.bib" "/path/to/org-bibtex-file.org" ("/path/to/org-bibtex-file2.org" . "/path/to/bibtex-file.bib"))) #+END_SRC

Basic configuration (recommended) ** PDF files Specify where PDFs can be found:

#+BEGIN_SRC emacs-lisp (setq bibtex-completion-library-path '("/path1/to/pdfs" "/path2/to/pdfs")) #+END_SRC

Bibtex-completion assumes that the name of a PDF consists of the BibTeX key followed plus a user-defined suffix (~~.pdf~~ by default). For example, if a BibTeX entry has the key ~~Darwin1859~~, bibtex-completion searches for ~~Darwin1859.pdf~~.

If the BibTeX entries have a field that specifies the full path to the PDFs, that field can also be used. For example, JabRef and Zotero store the location of PDFs in a field called ~~File~~:

#+BEGIN_SRC emacs-lisp (setq bibtex-completion-pdf-field "File") #+END_SRC

If ~~bibtex-completion-pdf-field~~ is non-nil, bibtex-completion will first try to retrieve the file specified in this field. If the field is not set for an entry or if the specified file does not exists, bibtex-completion falls back to the method described above (searching for key + ~~.pdf~~ in the directories listed in ~~bibtex-completion-library-path~~).

File specifications can be bare paths or follow the format used by JabRef, Zotero, Calibre, and Mendeley. This format also allows the specification of multiple files (e.g., the main paper and supplementary material). Examples:

~~File = {/path/to/article.pdf}~~
~~File = {:/path/to/article.pdf:PDF}~~
~~File = {:/path/to/article.pdf:PDF;:/path/to/supplementary_materials.pdf:PDF}~~

** Notes

Bibtex-completion supports two methods for storing notes. It can either store all notes in one file or store notes in multiple files, one file per publication. In the first case, the customization variable ~~bibtex-completion-notes-path~~ has to be set to the full path of the notes file:

#+BEGIN_SRC emacs-lisp (setq bibtex-completion-notes-path "/path/to/notes.org") #+END_SRC

If one file per publication is preferred, ~~bibtex-completion-notes-path~~ should point to the directory used for storing the notes files:

#+BEGIN_SRC emacs-lisp (setq bibtex-completion-notes-path "/path/to/notes") #+END_SRC

The names of these files consist of the BibTeX key plus a user-defined suffix (~~.org~~ by default).

At this point most people will be ready to go. Skip to [[#usage][Usage]] below to see how to use helm-bibtex and ivy-bibtex.

** Follow processor for helm

Invoking ~~helm-bibtex~~ or ~~ivy-bibtex~~ when point is on an [[https://orgmode.org/manual/Citation-handling.html][org-mode citation]] will automatically select that key. However, the default ~~org-open-at-point~~ on a org citation will take you to the corresponding bibliography entry. The following code will change this behavior to instead open ~~helm-bibtex-follow~~ when following an org citation by entering ~~RET~~ or clicking on it:

#+BEGIN_SRC elisp (setq org-cite-follow-processor 'helm-bibtex-org-cite-follow) #+END_SRC

Note in the case of an org citation with multiple keys, the above code will not preselect any entry when the ~~[cite:~~ portion is selected. See [[https://github.com/tmalsburg/helm-bibtex#use-ivy-bibtex-as-an-org-cite-follow-processor][here]] for the ivy alternative.

Advanced configuration ** Customize layout of search results

The variable ~~bibtex-completion-display-formats~~ can be used to customize how search results are presented on a per-entry-type basis. The default is

#+BEGIN_SRC elisp '((t . "${author:36} ${title:*} ${year:4} ${=has-pdf=:1}${=has-note=:1} ${=type=:7}")) #+END_SRC

which means that all entry types are presented in the same way: authors, title, year, … In this format string, the numbers indicate how much space is reserved for the respective field. If there is a * instead of a number that means that this field gets whatever space remains. Here is a setup that uses a different layout for different entry types:

#+BEGIN_SRC elisp (setq bibtex-completion-display-formats '((article . "${=has-pdf=:1}${=has-note=:1} ${=type=:3} ${year:4} ${author:36} ${title:} ${journal:40}") (inbook . "${=has-pdf=:1}${=has-note=:1} ${=type=:3} ${year:4} ${author:36} ${title:} Chapter ${chapter:32}") (incollection . "${=has-pdf=:1}${=has-note=:1} ${=type=:3} ${year:4} ${author:36} ${title:} ${booktitle:40}") (inproceedings . "${=has-pdf=:1}${=has-note=:1} ${=type=:3} ${year:4} ${author:36} ${title:} ${booktitle:40}") (t . "${=has-pdf=:1}${=has-note=:1} ${=type=:3} ${year:4} ${author:36} ${title:*}"))) #+END_SRC

For this to work, you have to add ~~journal~~ and ~~booktitle~~ to ~~bibtex-completion-additional-search-fields~~. See next section.

** Fields used for searching

The default fields used for searching are: author, title, year, BibTeX key, entry type (article, inproceedings, …). The variable ~~bibtex-completion-addition-search-fields~~ can be used to extend this list. Example:

#+BEGIN_SRC emacs-lisp (setq bibtex-completion-additional-search-fields '(keywords)) #+END_SRC

** Symbols used for indicating the availability of notes and PDF files

#+BEGIN_SRC emacs-lisp (setq bibtex-completion-pdf-symbol "⌘") (setq bibtex-completion-notes-symbol "✎") #+END_SRC

** Different naming schemes for PDF files

If the PDFs files follow a different naming scheme than BibTeX key + ~~.pdf~~, the function ~~bibtex-completion-find-pdf-in-library~~ can be modified to accommodate that.

** Application used for opening PDFs

By default Emacs is used to open PDF files. This means that either DocView is used, or, if installed, the much superior [[https://github.com/politza/pdf-tools][pdf-tools]] extension which offers features such as incremental search in PDF files and creation and modification of annotations that are compatible with annotations created by Adobe software.

To configure another PDF viewer the customization variable ~~bibtex-completion-pdf-open-function~~ can be used. Here is an example configuration for the OS X PDF viewer Skim:

#+BEGIN_SRC emacs-lisp (setq bibtex-completion-pdf-open-function (lambda (fpath) (call-process "open" nil 0 nil "-a" "/Applications/Skim.app" fpath))) #+END_SRC

Here is another example for the Linux PDF viewer Evince:

#+BEGIN_SRC emacs-lisp (setq bibtex-completion-pdf-open-function (lambda (fpath) (call-process "evince" nil 0 nil fpath))) #+END_SRC

It is sometimes desirable to have both options (Emacs itself and external viewer) to open the PDF. The following adds an action with Evince as an external viewer bound to P, in addition to the regular Emacs viewer with p. The action works with ivy-bibtex; it would have to be adjusted for helm-bibtex (change the path to another viewer if necessary):

#+BEGIN_SRC emacs-lisp (defun bibtex-completion-open-pdf-external (keys &optional fallback-action) (let ((bibtex-completion-pdf-open-function (lambda (fpath) (start-process "evince" "helm-bibtex-evince" "/usr/bin/evince" fpath)))) (bibtex-completion-open-pdf keys fallback-action)))

(ivy-bibtex-ivify-action bibtex-completion-open-pdf-external ivy-bibtex-open-pdf-external)

(ivy-add-actions 'ivy-bibtex '(("P" ivy-bibtex-open-pdf-external "Open PDF file in external viewer (if present)"))) #+END_SRC

** Additional PDFs :PROPERTIES: :CUSTOM_ID: additionalpdfs :END:

You may store additional PDFs for a given entry, such as an annotated version of the original PDF, a file containing supplemental material, or chapter files. If the ~~file~~ field is used to link PDFs to entries (see section [[https://github.com/tmalsburg/helm-bibtex#pdf-files][PDF files]]), these additional PDFs can simply be added to that field. If the action “Open PDF file” is triggered, you will then be prompted for the file to open.

If the ~~file~~ field is not used but instead the naming scheme ~~bibtex-key~~ + ~~.pdf~~ (again see [[https://github.com/tmalsburg/helm-bibtex#pdf-files][PDF files]]), you can obtain the same behavior with:

#+BEGIN_SRC emacs-lisp (setq bibtex-completion-find-additional-pdfs t) #+END_SRC

All files whose name start with the BibTeX key will then be associated with an entry. It is then sufficient to name your files accordingly (for example with the [[http://askubuntu.com/questions/58546/how-to-easily-rename-files-using-command-line][rename utility]]). Examples:

~~bibtex-key-annotated.pdf~~
~~bibtex-key-supplemental.pdf~~
~~bibtex-key-chapter1.pdf~~

Note that for performance reasons, these additional files are only detected when triggering an action, such as "Open PDF file". When the whole bibliography is loaded, only the "main" PDF ~~bibtex-key.pdf~~ is detected.

** Other file types than PDF

If documents are referenced via the naming scheme ~~bibtex-key.pdf~~ but you are storing files in a different format than PDF, you can set the variable ~~bibtex-completion-pdf-extension~~ accordingly. Example:

#+BEGIN_SRC emacs-lisp (setq bibtex-completion-pdf-extension ".djvu") #+END_SRC

If you store files in various formats, then you can specify a list instead of a single file type:

#+BEGIN_SRC emacs-lisp (setq