I also realized, after my excitement about Ecto, that I already have access to a nice weblog editor tool, the weblog editor built into NetNewsWire, so I started my testing using that. NNW has support for a number of different blogging systems and API's. Most systems that NNW supports are using the Blogger API, and MovableType uses both the Blogger API and the MetaWeblog API. In the array of structs that metaWeblog.getRecentPosts returns, I included information about the category of the post. Unfortuanately NNW doesn't make that information available. I started experimenting with the NNW commands and observing which MetaWeblog API calls were getting made. When NNW opens up, it never issues a metaWeblog.getCategories call. So it doesn't know what the categories are. If you do refresh it does a metaWeblog.getRecentPosts - but no call to get the categories. The retrieved posts are shown categoryless even if that information is in the return results.

One of the big reasons that I didn't use w.bloggar on Windows was that it couldn't deal with categories. NNW supposedly can do it, but you need the MovableType support. The biggest problem for somebody in my shoes, is that the metaWeblog (and Blogger) API's doen't say what the client is supposed to do about categories. If someone knows the correct sequence of metaWeblog API calls to retreive a set of posts which will have their categories displayed properly, that would be a big help.

In frustration, I looked at the Holy Grail, er, Atom API, but there's no description akin to the one that I want. So, just to be even handed, none of the specs have enough detail in them.

API documentation / specs has been both postively and negatively affected by tools like JavaDoc. These tools make it easy to document the individual methods of a class, but they don't help much with the "sequence diagram" problem, of documenting the right choreography of method invocations.

Looks like I'll be stuck with my little CGI for a while longer. I could use NNW's blosxom directory support but then I'd just be writing files in the file system. I could use SubEthaEdit's live HTML preview and my CGI -- the CGI can lace in categories, and does trackback, pingback, and notification pings. A good implementation of the Atom or MetaWeblog API's should be able to trigger such notifications as well.