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

or

#+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