paperq: a tool for managing a reading queue of academic literature

jakobcreutzfeldt · 2014-01-25 16:22:02

paperq is a command-line tool for managing a reading queue of academic literature. It's usage is simple: you add files to the queue and then you run it without arguments to open the next file in the queue. The queue part of the code itself is rather simple but paperq also offers some other nice features:

Add files (-a option)
Remove a file (-r option)
Display info on a file. Given a BibTeX file, print the bibliographic information, otherwise print the file location (-i option)
List all files (or bibliographic information) in the queue (-l option)
Create an archive (tar.gz) of the papers in the queue, prepending the file names with the queue position (-z option)
Operate on any file in the queue, instead of the head, via the -n option
Peek at a file (open it, but don't remove it from the queue) via the -p option
Print a file (-t option)
Configurable file-opening command (xdg-open %s, by default)

Documentation is available in the README file or on the website (see below). A man page is also included.

I've been using it myself now that I finally stopped using Mendeley. I find it to be quite handy, so I've packaged it up to be shared with others.

Screenshot showing the bibliographic info:

Website
AUR

Last edited by jakobcreutzfeldt (2014-01-28 09:15:50)

jakobcreutzfeldt · 2014-01-27 21:47:36

I just released version 1.1:

greatly speed up printing bibliographic data by caching it to disk with zeptodb (optional)
change creating an archive from "-x" to "-z" since it makes more sense to me
some code cleanup and error checking

It's updated in the AUR.

marttt · 2014-01-27 22:14:45

Thanks very much for this! I can finally ditch some of my ugly scripts now. Have you considered adding other bibliographic data formats in the future? (Here is an interesting solution with YAML and Pandoc and, correspondingly, proper UTF-8 support.)

Last edited by marttt (2014-01-27 22:15:23)

jakobcreutzfeldt · 2014-01-27 22:41:10

I just uploaded version 1.1.1. I somehow missed a bug in which the first word of the author list was being chopped off. It's fixed.

marttt wrote:

Thanks very much for this! I can finally ditch some of my ugly scripts now. Have you considered adding other bibliographic data formats in the future? (Here is an interesting solution with YAML and Pandoc and, correspondingly, proper UTF-8 support.)

Glad to hear it could be of use to you! Honestly, this also just started out as a quick script but little by little I started adding more handy features.

As for other bibliographic formats, it could be possible. I'm mainly familiar with BibTeX, so I would need to see how the other formats look.

In all honesty, the bibliographic info printing could be greatly expanded: only journal articles are supported at the moment, and mathematical expressions in the titles aren't yet supported (i.e. greek characters). It might be more efficient in the long run to write a dedicated biblio parsing program that loads some pre-written BibTeX-parsing library rather than all the crazy sed work that's going on in there right now. If that's the case, then it's just a matter of loading some library for a different biblio file format in order to support it.

Trilby · 2014-01-27 23:10:04

This looks great, I'm about to check it out here. For the various source types other than journal articles (but still bibtex) you might be interested in checking out the btparse library. I recently adopted it in the aur to get it up and running for a little project of mine. btparse makes pulling various bits of data from bibtex references/databases very simple. It does not, however, handle formating of mathematical or other symbols. It has been abandonded by the upstread developer (I think) and I've tossed around the idea of trying to add these bits in myself - but this very low on my list right now.

I just tried it out - I'm getting a couple errors here, am I doing something wrong:

## before installing zeptodb
$ paperq -a Foster2000.pdf
/usr/bin/paperq: line 331: zdbc: command not found
The specified position is larger than the queue length.

## after installing zeptodb
$ paperq -a Foster2000.pdf
The specified position is larger than the queue length.

Every operation seems to exit with that same error message.

Last edited by Trilby (2014-01-27 23:18:28)

jakobcreutzfeldt · 2014-01-28 08:44:21

Crap ok, will fix now.

Edit: ok, both of those problems should be fixed. That ought to teach me not to make a quick bugfix release before bed. Hopefully everything should be working fine now.

New in 1.1.2:

Fix erroneous checking of bad position numbers (-n) when adding to a new queue (i.e. don't check when adding at all...oops)
Fix checking for the presence of zeptodb
Increase default bibcache-size to 1000 (it should be related to the total number of papers you expect to read, not to the max amount you expect to have in the queue, another brainfart)
Fix some regexps to account for different whitespace usage in BibTeX (the perils of converting personal scripts to public ones)

Last edited by jakobcreutzfeldt (2014-01-28 09:10:26)

jakobcreutzfeldt · 2014-02-23 22:11:55

OK, version 1.2 is up. The biggest change is that I wrote another program in C, paperbib, that handles the BibTeX parsing (via btparse) and bibliography formatting. I guess it also might be handy as a standalone program. Anyway, the result is that paperq should run much faster and it should be more robust in parsing BibTeX files.

Note that if you were using zeptodb to cache the bibliographies, you should first delete .local/share/paperq/bibcache.db before using the updated paperq.

Other changes:

Creating a tarball archive is now done via "-z" rather than "-x" because it makes more sense
There is a new option, "max-authors", which sets the maximum number of authors to print before truncating and printing "et al.". Set this in the config file at .config/paperq/paperq.conf.
btparse and libunistring are now dependencies

Please let me know if you run into any problems!

Enjoy!

Last edited by jakobcreutzfeldt (2014-02-24 09:25:20)

Arch Linux

#1 2014-01-25 16:22:02

paperq: a tool for managing a reading queue of academic literature

#2 2014-01-27 21:47:36

Re: paperq: a tool for managing a reading queue of academic literature

#3 2014-01-27 22:14:45

Re: paperq: a tool for managing a reading queue of academic literature

#4 2014-01-27 22:41:10

Re: paperq: a tool for managing a reading queue of academic literature

#5 2014-01-27 23:10:04

Re: paperq: a tool for managing a reading queue of academic literature

#6 2014-01-28 08:44:21

Re: paperq: a tool for managing a reading queue of academic literature

#7 2014-02-23 22:11:55

Re: paperq: a tool for managing a reading queue of academic literature

Board footer