Literate & annotated bibliography — Nicolas P. Rougier
NOTE This literate and annotated bibliography is an adaptation of the idea Managing my Annotated Bibliography with Emacs’ Org Mode by Gregory J Stein.
The core idea behind literate bibliography is to have a single structured file where each entry corresponds to a reference. Information concerning an entry is stored as properties and two subsections allow to enter abstract and notes. To ease the manipulation, org-bib-mode provides a sidebar menu that displays the list of bibliograpic entries and provide tools to ease navigation. Under the hood, the org-bib-mode is the union of two modes:
- pdf-drop-mode that allow to drag and drop a file in order to add it to the bibliography using its doi that is searched automatically.
- org-imenu that allow to easily nagivate among entries and allowing various operations such as filtering entries, moving entries, etc.
org-bib mode is meant to be simple and robust (it is simple but not yet robust). If you need somethign more elaborated, have a look at the amazing org-ref mode by John Kitchin.
org-bib mode depends on pdf-drop-mode and org-imenu that needs to be installed. For example using straight.el:
(straight-use-package
'(org-imenu :type git :host github :repo "rougier/org-imenu"))
(straight-use-package
'(pdf-drop-mode :type git :host github :repo "rougier/pdf-drop-mode"))
The minimal document structure is a document with a single level headline that is used to store new entries. It is configurable via the org-bib-unsorted-header variable (default is “Unsorted”).
#+LIBRARY-PATH: ~/Documents #+LIBRARY-FILE: ~/Documents/my-bibliography.bib * Unsorted
You need to ensure pdf-drop-exiftool-path and pdf-drop-pdftotext-path points
to relevant binaries (these are needed to extract information from PDF
metadata (exiftool) or PDF content (pdftotext)). Last step is to tell org-bib
where to store PDFs. This is done via the #+LIBRARY-PATH keyword that you can
set at the top of your org-file. If you don’t, the current directory will be
used. PDF will be copied and renamed automatically if you set the
corresponding options.
| Key | Description | Key | Description |
|---|---|---|---|
i | Show org entry | v i | Set view mode to org entry |
a | Show abstract | v a | Set view mode to abstract |
n | Show notes | v n | Set view mode to notes |
= | Show preview | v p | Set view mode to preview |
b | Show bibtex | v b | Set view mode to bibtex |
u | Show URL | v u | Set view mode to URL |
p | Show PDF | v p | Set view mode to PDF |
v <return> | Exit view mode | ||
e | Export to bib file | f | Filter entries |
t | Tag entry | m | Move entry (refile) |
? | Mark entry unread | ! | Mark entry read |
M-<down> | Move entry down | M-<up> | Move entry up |
<tab> | Toggle current section | S-<tab> | Toggle all sections |
S-<left> | Next page (PDF view) | S-<right> | Prev page (PDF view) |
The simplest way to add a new entry is to drag and drop a PDF file onto the org buffer. The PDF will be parsed to try to identify a DOI and the corresponding bibtex item will be collected from the crossref.org server. The new entry will then be created below the Unsorted header (whose name is configurable) and the file will be renamed and copied to the library folder.
If this procedure fails for some reason, you can also enter a new entry manually or using the org-bib-from-pdf, org-bib-from-doi or org-bib-from-bibtex helper functions. In the latter case, no file will be automatically associated but you can later add a file into the library folder and rename it to “year - title.pdf” (replacing year and title with the actual year and title from the entry).
An entry is made of a properties block with two sub headlines (Abstract and Notes). You can edit any properties and add or remove them. But be careful to not remove bibliographic properties or else, the conversion to bibtex may fail because of some missing fields that are required.
To export the library to a bib file, you can use the org-bib-export command
(that is bound to the e key on the sidebar). The export filename will be deduced from the org filename unless a #+LIBRARY-FILE: is defined at the top of the org file.
You can filter the sidebar view (f) usin any kind of filtes. Here are some
example searches (note the absence of spaces):
- Articles published in 1984: YEAR=1984
- Articles published between 2000 & 2010: YEAR>1999+YEAR<2011
- Journal articles: TYPE={article}
- Papers by Knuth: AUTHOR={Knuth}
- Article published in a journal: JOURNAL={The Computer Journal}
See also Advanced searching from the org website.