miniref: Minimalist Reference Management Using the Command Line

miniref is an experiment at creating an academic reference manager (in the sense of Zotero), but for the command line and with a minimalist flavour. It is strongly inspired by projects like Cobib and fast-p (the latter which appears to originate the idea of using fzf for searching PDF literature).

Requirements

fzf (available via many OS package managers)
xpdf
Standard Unix/Linux shell utilities (originally developed under OpenBSD 7.3 against sh; POSIX compliance not guaranteed).
Python 3 (no external package dependencies)

Installation

Install fzf
Copy scripts to a location on your $PATH (e.g. ~/bin; redefine PATH=$PATH:$HOME/bin in your .profile if necessary)
Optional: export MINIREF_HOME=/path/to/my/references in your .profile (defaults to $HOME/miniref)
Optional: Add suggested aliases and functions to your shell config (e.g. .bashrc)

Introduction

The basic idea is that each reference is a directory with a human-interpretable and meaningful name that we will call the reference identifier. A suggested naming scheme is firstAuthorSurname + publicationYear + firstTitleKeyWord. For example, we might use turing1936computable as the reference identifier for A.M. Turing's 1936 paper "On Computable Numbers, with an Application to the Entscheidungsproblem".

Currently Implemented Features

miniref currently implements the following features:

Managing References

refman.py -e -s https://www.cs.virginia.edu/~robins/Turing_Paper_1936.pdf turing1936computable

creates the directory turing1936computable at location $MINIREF_HOME and populates the newly created directory with the specified PDF file (both HTTP(S) URLs and local paths are supported). In addition, the newly created directory is populated with a minimal ref.ris file, for storing citation information (e.g. author, title, publication year) in RIS (RefMan) format. Thus, $MINIREF_HOME now looks like this:

miniref/
`-- turing1936computable
    |-- Turing_Paper_1936.pdf
    `-- ref.ris

In the previous command, the -e flag opens ref.ris in $EDITOR, for manual entry of citation information. Note that in Google Scholar, you can get RIS-formatted citation information by selecting 'Cite' → 'RefMan' for a search result. If you set your browser to open files of this type in-place, you can make use of the -e flag for pasting citation information from Google Scholar.

Instead of relying on manual RIS data entry, it is alternatively possible to fetch RIS data automatically, by providing a DOI. We can amend our existing reference as follows:

refman.py -i doi:10.1112/plms/s2-42.1.230 turing1936computable

We can also use refman.py as follows, to the same effect:

cd $MINIREF_HOME/turing1936computable
refman.py -i doi:10.1112/plms/s2-42.1.230 .

Tagging a Reference

refman.py -t @to_read -t @computabilty_theory turing1936computable

assigns the tags @to_read and @computability_theory to our reference, using the file tags to store tags. Thus, $MINIREF_HOME now looks like this:

miniref/
`-- turing1936computable
    |-- Turing_Paper_1936.pdf
    |-- ref.ris
    `-- tags

We can untag a reference (i.e. remove a specified tag) as follows:

refman.py -u @to_read turing1936computable

Searching and Viewing References

Use refsearch.sh to search using fzf. You should see something like this:

The upper pane displays a list of references. For the selected reference, the lower pane displays:

Citation information (ref.ris)
Tags (tags)
Notes (cat of .txt files)

Incremental search (i.e. by typing) is currently applied to:

Reference identifiers
Contents of ref.ris file
Contents of tags file
Contents of any .txt files (e.g. notes)

Hitting Enter ↵ executes a shell in the directory of the selected reference.

Hitting CTRL-O opens the first PDF (if available) of the selected reference.

Hitting CTRL-R forces a reload of the upper and lower pane contents.

Roadmap

Use --listen to automatically perform reload() on file change using inotify
PDF full-text search / keyword extraction

pafoster / miniref