Archive for February, 2005

Commons Lang 2.1

Sunday, February 6th, 2005

Commons Lang 2.1 seems ready for release. There’s nothing too exciting or important left on the Bugs list and we’ll need to give Hani some warning to get his bile ready, but otherwise things look good.

As each passing year finds Hani getting a little older and more senile, the obvious targets will be:

  • Size of jar. 0.1-dev (whatever that was) was 29k. This latest release will break 200k.
  • Maven website. Yup, yup.
  • Over a year since the last release.
  • Lack of a detailed guide to walk you through how to use it.
  • It’s a stupid idea anyway, people should code their own utils.
  • Too many overloaded methods, people should code their own wrapping methods.
  • Ass-caressing clover output which allow the developers to think they’re doing something right.
  • Two enum packages! The swines.

Jakarta download pages

Sunday, February 6th, 2005

Much of my spare time over the last month has been spent on the Jakarta website, having a big spring clean. Many pages are gone/moved to www.apache.org, the 3-tier approach is embraced, the Anakia or XSLT option is gone and it just uses XSLT now, the site has stopped trying to link to various other Java@Apache projects all over the place and instead just has the afore-mentioned index of Java@Apache (http://jakarta.apache.org/site/java_at_apache.html) and it’s focused on being the site for Jakarta now and not a reusable site-builder for any project at Jakarta.

A lot of other things have been done (http://wiki.apache.org/jakarta/SiteInfo), but that’s the general top-level view. Next up is a rethink of the infamous download pages. They were initially a stop-gap solution to get people to use the mirrors asap, but haven’t changed since then. It’s pretty obvious what the problems are, the pages are huge, source and binary are on different pages, the pages are huge etc. So I’ve had some XSL fun (fear the XSL) and have a site of download pages created from a single download xml (http://jakarta.apache.org/~bayard/jakarta/site/downloads/download.html). Bear in mind that the [preferred] stuff is the mirroring, so most of the links won’t work as there’s no .cgi in place here.

That’s all that’s really left before putting it to a vote, figuring out how to handle the cgi, and making sure my downloads.xml is up to date (it’s not).

The underlying system itself is viewable at http://svn.apache.org/viewcvs.cgi/jakarta/site/xdocs/downloads/, it generates xdoc files which are then converted by the main site xslt into the html stuff.

Computer books - where are they going?

Saturday, February 5th, 2005

I’ve been told by a few different sources that the computer book industry is not selling as well as it used to (or at least the part of said industry that I am most interested in, open-source and Java). The all pervasive web is becoming a major competitor I think, a couple of times now I’ve stood in a bookshop with a book and decided that I should just google instead.

The responses by various publishers to try and combat this change, or ride the new wave are interesting. SourceBeat are an obvious example here, go online so you can skip the dead-wood and offer many updates. Matt Raible recently blogged about how the problems of updates (http://jroller.com/page/raible/20050203#thoughts_on_spring_live_updates), juggling the new update with the new release.

O’Reilly have two obvious solutions to the problem. One is their deal with InformIT to create Safari, an online library of books. It’s a damn good idea with but one problem; reading a book on a computer still sucks compared to the real thing. Still, it’s probably a better idea than the SourceBeat plan as all it requires is that the already computer-formatted dead-wood books be uploaded to the site and brings in a lot more money. It is still competing with the mightly Google, I recently cancelled my subscription for two reasons: 1) I can google, 2) I have a stack of books to read, both at home and work.

O’Reilly’s other idea is the Developer Notebook series. It’s another sign that O’Reilly have their finger on the pulse; books are too long nowadays. There are two types of book, an educationally informative book and a reference book.

Reference books used to be king. Take Java in a Nutshell, it used to be the best book in Java by a furlong. Back in the ‘old days’ when people still had dial-up and Internet lag was a common occurence. Nowadays, I can store the JDK javadoc and the J2EE javadoc on my watch (must look to see if any browser can read a .html.gz file). So reference books are much less important. O’Reilly have made two noticeable attempts to find new legs in the reference world; the pocket reference book and the Cookbook series. I own something like 20 pocket references, and I’m increasingly finding them to be worthless. I’ll probably go this entire year without opening a single one of them. Cookbooks are better, though they suffer from the brilliance of the first book (Perl Cookbook) and subsequent titles have a hard job matching its standard. Manning are into cookbooks too (Recipe series), I’ve not read one of them yet, but they’ve got quite a few coming out.

Size is a good thing in a reference book. A nice big fat reference book can quite simply refer to more, but it also must make the book more expensive to create; especially as the index is a very important part of the book.

The other side is the educationally informative book. This is a book that teaches you a topic. It’s not designed to be used again and again, but to be put on a shelf once read and look pretty. Sometimes you’ll pull it down, but generally it’s served its purpose when you read it. All the great books are in this area, probably because they’re designed to be read while a reference book is designed to be referred to. They can flow and allow the author to come through, while a reference has to be structured. Of course, many of the worst books are in this area too as they fail to flow and they allow the author to come through :).

Size is not such a good thing in an informative book. I don’t want to read 1000 pages of Tate’s Kayaking stories (sorry Bruce). In fact, I want to read the minimum number of pages possible to get the maximum amount of information back. The Developer Notebook series seems to be an attempt to create informative books that are short and efficient. 200-300 pages seems to be the norm, though they should really get aggressive and try to get them down to 150-200 pages. The marketing suggests that Developer Notebooks are the random jottings of alpha-geeks, droppings of pure ichor that we readers should lap up in our ravenous swarms.

Well, they could be. Until the series builds a reputation for maximum efficiency, it’ll be hard for a reader to choose one over a larger more standard text. We may need the shorter, quicker book, but we tend to make a lot of bad choices that aren’t what we need. Next thing you know, we’ll be walking away with the 1000 page, 7 author, Wrox book on Mono and not the 300 page developer notebook. To that end, the notebook needs to be first to market, and first to market by a good stretch of months. It can afford to be though, it’s smaller and more agile. Indeed, the core features of the notebook series might end up being quite familiar (release early, release often). There’s one self-inflicted torpedo in the O’Reilly water. To get a quick release, they have to tame the alpha-geek. This involves (I presume) providing the author with a very detailed structure that the alpha-geek must fit into. Thus, the weeks spent deliberating on how to structure each chapter and whether to come up with some quirky insane idea are quashed and saved. It’s an idea we’ve seen before in the other type of book (reference book for those not paying attention), and this leads to a rather unfortunate conclusion, the notebooks are boring to read.

Now, that might be a bit unfair. I ordered my first notebook today, so all my reading up til now is via downloaded chapters or time in stores (I look at computer books in stores a lot though), but the enforced structure makes me want to scream, Harold’s Java IO would not be the classic it is if he’d had to fit into this, and this is the kind of book we need in the future.

Still, O’Reilly have most of the right idea. All they need to do is release the reins on the authors a bit, allow great notebooks to happen. Manning are characteristically keeping a close eye on the O’Reilly train. They have their Quickly series (XSLT Quickly was 320 pages and came out in 2001, Hibernate Quickly is apparantly in the works, wonder how many others?). It seems like a natural competitor to the Notebooks.

I concentrate on Manning and O’Reilly, and to a lesser extent Apress, as they’re the most involved with open-source topics and I presume the furthest away from the old-model of book publishing. Apress don’t really seem to have gone as far as the other two in trying new modes of publishing, but I suspect they’ll have to follow.

In the open-source world, there’s an interesting competitor to the Manning/O’Reilly, the open-source project. While an open-source group is unlikely to churn out a 1000 page reference, with detailed indexing and a plush looking cover featuring a cute bush-baby, a 200 page guide is a different matter. David Gilbert sells a user-guide in PDF format for JFreeChart, while Ceki Gulcu published a book on log4j many moons ago. JBoss also provide their own books. Ceki’s (http://www.qos.ch) is an especially good example as it shows some similar usage to SourceBeat’s subscription model.

Going forward, it seems to me that we need two things. The first is good software to write books with. Most are written in MS Word, and if that’s the way it has to be, so be it. Some are written in Tex, and some in Docbook. A few new ones are written in OpenOffice I think, and a few have lots of custom bits in them. As long as they can export nicely to PDF, it’ll be good.

The second is a cafepress (http://www.cafepress.com) style service for books. This is tricky part I suspect as there’s a fair amount of work that goes into turning a Word file into something that can actually print onto paper. This could still be doable, upload word file to server, allow people to pre-order it until the pre-orders equal the cost to turn the word file into a printable copy (though some obvious problems in making sure people’s credit cards don’t cancel, or they don’t change their mind), then charge people the price of printing, with popular books being able to either drop in price or make more profit. You could even offer different qualities of printing.

Hook this to the Gutenberg project to expand way beyond computer books :) They’re just text files, but it must be a lot easier to deal with a typical fiction book than a computer book with lots of examples etc.

I wonder if anyone tried to push such an idea in the mad era of the dot.com, or if there’s someone out there right now offering this service.

Anyways, to bring a long ramble to an end, more smaller, tightly focused books please :)

Java @ Apache

Thursday, February 3rd, 2005

I don’t think I’ve mentioned this page yet. A, hopefully complete, index of all the Java projects at Apache:

http://jakarta.apache.org/site/java_at_apache.html

Automatic unit testing of Javadoc

Tuesday, February 1st, 2005

Something I’m increasingly trying to do in the Commons Lang code is to copy any examples from the javadoc into the junit tests. It’s embaressing when one of them is wrong :)

It’d be nice if I didn’t have to copy them (and have them get out of sync). Something xdoclet’y perhaps?

I guess a simple solution would be to pull the example code out into a separate tree of examples; hook the tests up so they run the examples as well as their own harder tests, and then have the javadoc have a url to the example.

Slightly better would be if we could plug a tiny bit of code into the javadoc doclet to let us add a new javadoc tag that would inline a block from the example. Something like @example org/apache/commons/lang/StringUtilsExample.java#foo

and in the example it would be something like:

public class StringUtilsExample {
   ... various bits of code ....
   //#foo
   piece.of.example.code();
   //#/foo
}