Development [LWN.net]

The Free Software Directory's Documentation Vacuum

One of the numerous duties your development page editor must do each week is to scan a list of web sites for announcements of new and updated open-source software packages. Several criterion are used to select software announcements for inclusion in the weekly edition. The most important points include usefulness of the software to a wide range of people, the existence of documentation describing the project, and availability of documentation describing the changes in the just-released version.

Over the years, many projects have been added to this list, and many others have been removed, due to either project stagnation, or ineffective project documentation. The list itself is a bit too ragged for publication here.

One site that gets visited one or more times each week is the FSF/UNESCO Free Software Directory. It contains a list of the most recently changed open-source applications, as well as categorized listings of over 3,000 packages. It's a great place to find just about any kind of software you may need, and get a real feel for the wealth of open-source applications that are available.

Unfortunately, a common problem has been observed with the majority of the new releases listed on the site: discovering what the changes are in the latest versions. We'll look at the latest release of etherboot as an example. We're not picking on this particular project in any way, it's just one of many cases.

Starting with the FSF/UNESCO Free Software Directory, we see an interesting package listed in the Ten most recently updated entries section:

etherboot - [The GNU General Public License, Version 2] - 2004-06-28 Makes boot ROMS

Cool, there's a new version this week. Clicking on the link to the etherboot announcement, we see, among other things,

Version 5.3.8 (devel) released on 2004-06-28.

So far, so good. But here's where things begin to get dicey. The announcement page links to the source code (stable version only), various mailing lists, documentation, and the project web page. But we want to get development version that we saw in the previous announcement.

Moving to the project web page, we get a typical project presentation with the usual links. Let's see if there's anything about the new release under News. Nope, just a link to the project's SourceForge page. Finally, we're getting somewhere. Using the age-old axiom, Use the Source, Luke, we download version 5.3.8. Interestingly, the download date for this release has mysteriously changed to June 12, 2004. Downloading takes us through the usual series of intermediate steps to select a local server, before beginning the operation.

Now, we have a local copy of the source file. An invocation of tar yields the source tree. Change into the source tree, and FINALLY, there are some release notes:

As of Etherboot 5.3.8: There is no longer a default target for make. You must specify an argument to make. Help text is now provided to indicate possible make targets. binutils-2.14 is no longer needed in order to compile images. The symbolsrec feature is not used, so older binutils (ld) should work.

That took an awful lot of clicking through web sites across the net, the need for a lot of disk space, some bandwidth, the knowledge of dealing with bunzip2 and tar, and a fair amount of patience.

There really ought to be a simpler way to get this kind of information out. Often, your griping (but not necessarily grumpy) editor simply moves on to the next project in search of more accessible documentation, and the cool new software doesn't get the attention that it deserves.

Finally, a frequent problem with software announcements is the lack of any kind of date associated with a new version announcement. Free software writers would be well advised to add a few trivial bits of information to their releases, and make sure the information is easy to find. Doing so would probably do wonders for expanding the user base.

Comments (5 posted)

System Applications

Database Software

Using CachedRowSet to Transfer JDBC Query Results Between Classes (O'ReillyNet)

Sean Eidemiller works with the Java Database Connectivity (JDBC) API on O'Reilly. "JDBC developers have always needed to keep a database connection open while pulling query results. But with the CachedRowSet in J2SE 1.5, it's now possible to disconnect and then get results. Sean Eidmiller shows the advantages of this approach."