bibtex-utils.el

bibtex-utils.el provides some simple conveniences for working with BibTeX files. More elaborate features are provided by helm-bibtex and org-ref.

To use this package, add the following line to your .emacs:

(require 'bibtex-utils)

Navigation

Two new functions are added for navigating entries, bu-next-entry and bu-previous-entry, bound to M-n and M-p.

Keywords

bibtex-utils adds a hook to bibtex-mode-hook. The hook will run whenever a .bib files is opened, parsing all the keywords present in the file and storing them in a local variable. Those keywords will be used to provide tab-completion when the user calls the function bu-make-field-keywords.

When point is within a bibtex entry, calling bu-make-field-keywords will prompt the user for keywords, with tab-completion. If a keywords field already exists, the keywords will be added to it. If not, a new field will be added to the entry. Hitting return on its own will complete the process. Any keywords not already in the local variable are added to it.

You will probably want to bind this function to a key:

(eval-after-load 'bibtex
'(define-key bibtex-mode-map "\C-ck" 'bu-make-field-keywords))

These functions assume that keywords consist of phrases with no commas; commas are interpreted as separators between keywords. Newlines are ignored, so keywords can span multiple lines.

Cleaning entries

When we add bibtex entries we collect from online sources, they often contain fields that we don’t wish to keep. bibtex-utils provides a convenient way to delete these fields when you run the command bibtex-clean-entry. This command is provided by the built-in Emacs bibtex-mode, and is bound to C-c C-c by default.

bibtex-utils adds a hook that calls the function bu-bibtex-clean-entry-hook. This will delete any fields listed in the variable bu-bibtex-fields-ignore-list from the entry. By default, this variable is empty, but you can customize it to contain any fields you want automatically deleted from entries.

I found this very useful function on Nick Higham’s blog, where it was contributed by a user named Bernhard. Thanks Bernhard!

Viewing documents

bibtex-utils also provides a mechanism to open the documents (pdfs, webpages) for a given bibtex entry.

pdfs

For the moment, this system assumes that all of your pdfs are in a single directory, saved in the customizable variable bu-pdf-dir. By default this is set to ~~/pdfs~. You can also specify the path to your pdf viewer in the variable bu-pdf-viewer. The default is nil, which tells Emacs to open the file in Emacs itself. I highly recommend you do this, after installing the pdf-tools package.

For now, the files must be named the same as the entry key, with the ‘.pdf’ suffix added. This will become customizable eventually.

doi

If you store article doi codes in your entries, in the field doi, bibtex-utils can look those up for you too. At the moment, this only works with firefox with the doi protocol extension, but it may be possible to tweak it to use Chrome with a different extension. The variables to play with are bu-doi-resolver and bu-doi-prefix. Following a doi link will invoke the command bu-doi-resolver bu-doi-prefix doi, which by default is firefox doi:10.XXX.XXXX.

url

If you store the article url in the url field, bibtex-utils can open the url using Emacs’ default browser, via the function browse-url.

How it works

When you invoke bu-open-doc from anywhere within a bibtex entry, bibtex-utils first looks for the pdf and opens it if it finds it. If it doesn’t, it will check for a doi, and open that if it exists. Finally, it will try to browse to the url. I’m planning to make the order of priority customizable in the near future.

If you call bu-open-doc with a prefix argument (i.e., C-u M-x bu-open-doc, or C-u RETURN in a bibtex search buffer), it will ignore any local pdf files, and try to open the doi or url instead.

bu-jump-to-doc

This function will jump from a bibtex citation in a source document directly to the document itself (i.e., the pdf or webpage). It’s a wrapper to bu-open-doc that works when you’re not already on the bibtex entry. If you use bibtex keys in different file types (org mode, markdown, latex etc), you may want to bind this to a global key:

(global-set-key [f9] 'bu-jump-to-doc)

Note: bibtex-utils does not provide a way to jump from a bibtex citation to the bibtex entry in the .bib file. Reftex already does this. The function is called reftex-view-crossref, which is bound to C-c & by default.

BibTeX Search

When you search for entries from BibTeX mode, the results are placed in a buffer called *BibTeX Search*. This is a read only buffer in BibTeX mode. I have added a new minor mode, bibtex-search-minor-mode to make it possible to add some convenient key-bindings to use here:

key	command
b	bury-buffer
k	kill-buffer
q	kill-buffer
n	bu-next-entry
p	bu-previous-entry
RET	bu-open-doc