I won’t be giving up on maintenance of the main Alexandria program. It’s a useful program in its current state, and it has a few bugs which are preventing it being properly stable for its users. They need to be sorted out, certainly. But the addition of new features into the pre-existing codebase is just too… messy. Especially without a plan.

So, I’ve decided to create a new little side project for myself and hack on that instead. Apart from anything else, it should help lift my current development funk surrounding Alexandria. If it goes badly, I can at least learn some things from the experience and avoid them when I return to adding features to Alexandria directly. If it goes really well, it may replace the entire Alexandria codebase (this is quite unlikely). In any case, it’ll be called Palatina, after Bibliotheca Palatina. To begin with, I’ll be writing short articles here about how the domain might be worked out. Then, I might make a few diagrams, write a few code fragments… We’ll see how it goes. Eventually, a wiki and a source repository might be necessary.

If anyone wants to comment constructively on my work with Palatina, drop me a line and I’ll create an account for you on this journal - you’ll know my e-mail address from the Alexandria mailing list.

Okay, back to listview.rb and I’ve found the column visibility code in the method setup_listview_columns_visibility. I can see that the set of booleans from the gconf prefs is being set up into an ordered array - cols_visibility - to be correlated with the ListView columns in a loop just below. The ordering must be wrong…. I split the Emacs editor window horizontally and try to find the order in which columns are added to the ListView in the upper pane while keeping the cols_visibility in the lower pane. Right! In setup_books_listview the title column is set up first (but it can’t be turned invisible, of course) the each of the columns in TEXT_COLUMNS are added in turn, followed by all the CHECK_COLUMNS and then the rating column. Oh, and a tags column that’s getting set up but not displayed (adding that to another Post-it!). Lets write all that in a list.

Now to compare it with the cols_visibility matrix.

Okay, I think we have the superficial cause of the problem identified. Let’s change the order in that array of booleans. First, though, my cat wants to say hello…

So after playing with Sibbie for a while, it’s back to Alexandria. I fixed the order of the variables in cols_visibility to match the columns - it’s a 3-line fix. Well, I’ve noticed a few other issues along the way, so while I’m at it, I touch up the preferences dialog a bit, rearranging the checkboxes and adding a preference option for Tags. I commit my changes to subversion, r958. Then I go to the bug report on RubyForge, add a comment and mark it closed.

So, that’s another snag uncovered and fixed. Now for the point of the article: why did this type of bug arise in the first place? Simply because the original code (Laurent’s, not Joseph’s, by the way) was designed for a small system in which it was easy for the programmer to check that the column array and the boolean array were in sync. It must have broken gradually as code was added and moved about, it was inevitable really. If the code were a bit more “type-safe” (using that term in its loosest sense) then the task of remembering the ordering of arrays would be left to the software, not the programmer. I haven’t even fixed that, so the weakness remains. This is the kind of weakness, present throughout the Alexandria code, that needs to be addressed in the future design of Alexandria.

I should clarify. For tracking a handful of bugs, maybe even a pageful, the Tracker is fine. You can see most of the status details you want in the summary list. For following up on a single bug, it’s pretty good too: it sends out notification e-mails, you can attach files, change priority…. There are a few administrative nigglesL because I came to the Alexandria project after Laurent Sansonetti left it, I’m still not on the list of developers to whom a bug can be assigned; I get two e-mails for every change on a bug I’ve been working on, one direct from the Tracker, and one from the alexandria-bugs mailing list (which also notifies me of changes to bugs I haven’t been working on). But it works okay in small scale.

The problem is when we have a few hundred open bugs, as happens when a project lies dormant for a year or two. Sorting them out - finding duplicates,  removing obsolete reports, requesting more information from poor reports - is inevitably slow because of the nature of web applications. I really want to be able to grep through the reports, assign tags to groups of them at a time, sort them according to arbitrary conditions. What I’d like is a way to take the data home with me… A few weeks ago I was almost ready to write a scraper application to scour the four Alexandria Trackers and save each complete bug report as YAML or XML. I may yet write it.

In the mean time, there’s L.C. Karssen, who’s doing the hard work of sifting out duplicates, requesting extra information, closing old reports, confirming new reports and finding new bugs - all just using the old Tracker I’ve been complaining about. And it looks very likely that he’ll be able to get us down below a single page of (50) open, relevant, real bug reports within the next few days. That should make it much easier to use the Tracker to deal with new bug reports. Thanks Lennart!

Then, of course, we’ll have to tackle the Feature Requests Tracker, and translate some of those tickets into requirements on the Alexandria Wiki.

Apart from looking through the Alexandria manual to find the current described features of the program, I’m going to go through the mailing list archives for various discussions of requirements. Alexandria users can help too: register on the wiki (it’s very quick) and add your requirements (in an orderly fashion, of course). I’ll probably be running around re-organizing things anyway, hopefully making it easier for me to formulate a detailed statement of requirements. I think anonymous edits are still possible at the moment, but it’s better if you have an identifiable voice for your requested features. It’s better for the developers too, since we get a handle on you as a user and can see all the requirements you have as part of a big picture.

This is all very new and experimental for me; I’ve never helped to run a wiki before. With any luck, it won’t all end in chaos. (I’m such an optimist!)

So, we’ll need a modeling program, and we should probably just choose a single one which we can all use. Gaphor is a clean and simple UML modeling program for GNOME. It is, naturally, free software,  released under the GNU GPL. It’s written in Python, is easy enough to install and very easy to use. It supports class, sequence and communication diagrams: the main diagrams we’ll be interested in.

It also produces nice, sharp, easy-to-read diagrams which can be exported to SVG or PNG.

It also has a plugin system (and docs to help you write new plugins) if we ever need extra features. If I could magically add a major feature, it would be a plugin to allow collaborative editing of models (rather like Gobby does with source files). In the mean time, we can just push gaphor files around via Jabber file transfer and use chat to discuss the changes we’re making. The gaphor file format is stable and XML-based (so it can be stored in subversion).

Like the ISBN example above, I’m going to be coming up with a few design sketches to suggest how various parts of Alexandria’s domain might be modeled. But they’re just preliminary ideas; we need to make sure that our eventual model matches the use cases rather than the other way around.

If you just want to have a look at the code, you could simply download the latest tar.gz package. However, if you want to keep up to date with the developers as they work, you should do a check-out of the Subversion repository. If you don’t know anything about Subversion, there is an excellent introduction in the free book Version Control with Subversion. But, to begin with, you can just install the subversion package and issue the following command from the terminal (all on one line):

svn checkout svn://rubyforge.org/var/svn/alexandria/trunk/alexandria alexandria

This will create a new alexandria directory containing the current source of the main development branch of Alexandria, we often call this alexandria SVN for short.. If you just unpacked the tar.gz archive, the directory will be called alexandria-0.6.2 but in any case I shall refer to it as the alexandria directory.

Move into that directory and look around. In particular, the INSTALL file describes the various dependencies of Alexandria. The main requirements are, of course ruby (Ruby 1.8 in particular) and ruby-gnome2 (the bindings library which allows us to use Ruby with GTK+ and GNOME). Also required is ruby-gettext which allows the program interface to be translated into multiple human languages. Make sure you have these packages installed. If you’ve installed the binary of Alexandria already, most of the dependencies listed will have been installed automatically.

If you are on a Debian or Ubuntu-based system you should also install irb the Interactive Ruby shell (for experimenting with small fragments of Ruby code quickly).

Also in the alexandria directory is a Rakefile for building the code. Rake is the Ruby equivalent of make, install it with the rake package. Because Ruby is still very much a scripting language, the source files are not compiled. The building of the software only involves two stages: automatically generating some Ruby files and compiling the gettext translation files. For the latter task, you will need gettext and intltool packages, as described in the INSTALL file. Running the simple command rake in the alexandria directory will build the software.

To install the development version of Alexandria, run the command rake install as root: either quickly su to root and issue the command, run su -c ‘rake install’ or, more usually, run sudo rake install.

You should now be able to see the Ruby files, program resources and documentation being installed. Note that if you’re on a Debian or Ubuntu-based system, rake install will install the Ruby files in /usr/local/lib/site_ruby/1.8/ which is different from the location used by the deb installation. This is because of the way Debian handles Ruby. It means that you may end up with two competing copies of Alexandria on your system, and the development version will usually be detected first. Unfortunately, there is no rake uninstall task, but you can just remove all the alexandria files from /usr/local/lib/site_ruby/1.8/ by hand with: sudo rm -rf /usr/local/lib/site_ruby/1.8/alexandria* if you want to remove the development version.

Once you have installed Alexandria, you can launch it with the command alexandria or using alexandria --debug if you want to see more logging information. To see what another translation of the Alexandria looks like you can set the LANG environment variable as you launch the program: LANG=nl_NL.utf8 alexandria

You are now working with the development version of Alexandria.