Yabman: Yet Another Bibliography Manager

What is Yabman?

Yabman is for academics and researchers. It is a tool for managing bibliographic references created by Reid Priedhorsky. Key features are:

A well-designed user interface, supporting efficient search, browsing, and entry of references.
A very good data model, carefully designed in the style of John Carlis.
Sophisticated three-state hierarchical reference feature labeling: compare references like this. (Note: Yabman does not create such tables automatically, though I hope to have something similar in the future.)
Seamless interoperability with CiteULike.
Export of references to BibTeX format.
Yabman is free software under the GNU GPL.

Yabman currently runs on Linux only, though it's written in Python with the wxWidgets GUI toolkit, so ports to other systems are likely to be easy/trivial. I welcome patches.

Note that Yabman is still in early stages of development. It is not yet ready for general use. In particular, neither BibTeX export nor CiteULike integration is yet implemented.

The user interface and the data model are why you should use Yabman instead of some other bibliography manager.

Yabman is currently in a pre-alpha stage: I (Reid) use it daily for keeping track of my own references, but there are many features missing and a few bugs. Skills in Python, wxWidgets (wxPython), and possibly SQL will be helpful in your hacking.

I placed Yabman on SourceForge because, being a grad student, I don't have the time needed to really give Yabman the TLC it needs to bring it to a stable, fully-featured version 1.0. Please help!

Eventually, I'd like a co-maintainer or two who can actually put more work into it than I do. However, even a patch or two would be very helpful.

To get started hacking:

Download and install Yabman (below).
Join the developer mailing list (optional, but highly recommended).
Find a task in the bug tracker (or cook up your own, though discussion first with the mailing list is suggested).
Hack.
Send a patch to the mailing list with a short description of your changes. (svn diff is your friend for this part.)

Downloading

At this stage, it is best for you to just use Subversion to grab the source and keep it up-to-date. Install Subversion, then say:


$ svn checkout https://yabman.svn.sourceforge.net/svnroot/yabman/trunk/ yabman

This will create a directory called yabman. cd into it and start hacking!

Alternatively, you can download a tarball from the SourceForge file servers. However, I highly recommend that you opt for Subversion instead.

Installation

Prerequisites -- you'll need to install the following:

Python 2.3
wxPython 2.6
pyPgSQL 2.4
PostgresSQL 7.4

(Other versions are untested. Higher versions of Python, PostgreSQL, and pyPgSQL are likely to work. I welcome feedback and backwards-compatible patches to increase version compatibility, and also patches to make Yabman work with other RDBMS packages.)

After unpacking the tarball or pulling the source with Subversion, you'll need to:

Set up the database. Create a database (using createdb or equivalent) with whatever name you prefer, then initialize the schema by running the SQL scripts sql/update-*.sql in order, i.e.:
$ psql -f sql/update-001.sql $DBNAME $ psql -f sql/update-002.sql $DBNAME (etc.)
It is prudent to review the output and make sure there are no problems. If there were and it's my fault, please let me know.

If you want to populate the database with some sample data (this is optional), run the corresponding sql/sample-n.sql script after each update script. Not all update scripts have sample data.

Create a ~/.yabman file. I recommend copying doc/config-example and editing as appropriate.

To run the program, cd to src/ and say python gui.py at the shell prompt.

Upgrading from a previous version

The scripts in sql/ can also be used to update the database schema to the version required by the current software. (Note that the schema version is independent of the Yabman version.) Script update-n.sql changes the schema from version n-1 to version n. The scripts have the following (soft) guarantees:

Idempotency multiple runs have the same effect as one. (However, this depends on the RDBMS enforcing constraints.)
User data is never destroyed unless documented (see the release notes).

Note that user data may be *changed* in some cases to conform to the new schema. There should be no semantic changes unless noted in the release notes.

If you have schema version x (say select max(version) from schema_update; at your SQL prompt) and wish to update to the current version y, simply run all the scripts numbered x+1 to y in order. You may also wish to run the corresponding sample-n.sql scripts.

There are also sometimes update reversal scripts. revert-n.sql reverts the changes made by update-n.sql. These are meant to be developer tools, and you probably shouldn't run them unless you know what you're doing. They may not be complete, correct, or even present.

Always back up your database before running any SQL scripts. (If you do run into problems, however, please let me know!)

How Searching Works

When you first run the program, you're presented with the basic search interface. Enter a list of keywords, separated by whitespace, into the text box. Keywords are case-insensitive; non-alphanumerics other than dash, apostrophe, and underscore are removed. The keywords have AND semantic, i.e. each keyword must appear somewhere in each result.

Example: Searching conferences for "human computer interaction" finds each conference where:

"human" is contained in name or abbrev,
and "computer" is contained in name or abbrev,
and "interaction" is contained in name or abbrev.

Depending on the number of hits, different things happen:

Two or more hits: A summary window is displayed.
One hit: The editor window for that entity is displayed.
Zero hits: A new, blank editor window is displayed. (Note: I know this is strange, and I plan to change it -- see bug 102.)

Search fields

References:	title, tags, author and editor names
People:	(see below)
Journals:	title, abbrev
Conference:	name, abbrev
Features:	topic name, topic abbrev, feature name
Topics:	name, abbrev
Institutions:	name, address

Searching for people

If the search string appears to be a fully specified name, i.e.

"William Clinton",
or "William Jefferson Clinton"

then a targeted search is performed. For example, both the of the above will find each person where:

the first character of the lowercased first name is "w",
and the lowercased last name is "clinton"

This is so the above searches match "W. Clinton" and "W. J. Clinton", which is useful because citations so often omit full first names.

If the search string appears otherwise, the rules above apply. The first name and last name fields are searched.