When the open-source model breaks down
I have a fairly simple requirement: I want to write a long technical document, using DocBook as the markup language, and I want to conveniently cite references to other publications. And I want it to run on Linux. That’s a simple requirement to state; I’ve discovered, to a reasonable standard of proof, that it’s by no means easy to achieve. In fact, I’ve spent an immensely frustrating few days just trying - and failing - to cobble together a working solution.
There are tools out there. I’ve been looking mostly at two: refDB, and JReferences. Both are open-source reference managers, that import a variety of formats, and can produce DocBook marked-up bibliographies for a given input document. In theory. RefDB is the more polished and complete of the two tools. JReferences is a one-man effort that seems to be moribund for the last couple of years.
I actually got a fairly long way with refDB. I have installed the software,
imported my references in RIS format, can query for particular refs and
generate output in DocBook format. The tool I really want to use, however,
would allow me to submit a document with <citation> elements in it, and the
tool would comb my database for matching references and selectively generate
formatted output. This process depends on having styles imported into refDB,
and this is where the problems started. When I import a style, the refDB client
goes into a busy-wait state, soaking 100% of the CPU and not terminating. I
tried in verbose mode, to see what the problem might be, and got a meaningless
cryptic three character error code. I surmised that there might be a problem
with the libdbi database drivers, so I got the
latest libdbi CVS head and tried to build it. After a bit of a false start, I
can build the drivers but can’t install them - the make install target breaks
when installing the documentation, because it doesn’t recognise the docbook
schema for the SGML files, for wholly non-obvious reasons. It’s at this point
that the “many eyeballs make all bugs shallow” maxim falls apart. For my
particular configuration, there is only my pair of eyes to look at the problem.
At this point, I would gladly pay for either a licensed product, or a support
contract, if I felt confident that I was going to get working functionality at
the end of the day. The notion that I have the source so I can fix the problem
myself doesn’t work here: I have limited time to spare for the task of getting
references into my document. There quickly comes a point when it’s easier just
to code the citatations by hand than to spend time grokking someone else’s code
and fixing problems.
The other tool I looked at briefly was JReferences. It’s a Java program, so I
felt comfortable that I could ascend the learning curve a bit more quickly if I
needed to. It has the right features on paper: a RIS importer (among others)
and DocBook exporter (among others), and a simple editor for viewing and
updating stored references. So, task one: convert my RIS-formatted collection
to BibTexML, which is JReferences’ preferred internal format. There’s a
command-line utility to do just that. Run it, and it produces … nothing. No
output and no errors. OK, so it’s a program that hasn’t been touched for at
least two years according to the CVS log at SourceForge. Maybe running it
inside a Java debugger will reveal a simple fix. So, I get the source, drop it
into Eclipse and …. and it won’t compile. Not even close. There seems to be
two different package layouts competing with each other. Lots of
inconsistencies that Eclipse barfs on. Worse, many of the problems are
incompatibilities with bibtexml.jar, which is only distributed in binary form
that I can find. I can’t imagine how this program ever worked properly. I can’t
see any test code at all. There’s not actually that much code all told, and I’m
fairly sure I could, if I wanted, fix it up.
But why bother? It would be significantly easier for me to start over with an empty project in Eclipse than spend time understanding, fixing, and extending the existing codebase. Open source, code re-use, and so on only helps if the code is functional, comprehensible and working. Lose that, and you have worse than nothing.