Solar 0.5.0 Released

Hot on the heels of Friday’s 0.4.0 release, we have today’s 0.5.0 release of Solar, the simple object library and application repository for PHP. It’s mostly minor bugfixes, with a couple of minor feature adds, all as a result of the ongoing end-user documentation effort.

You can view the change log here, but the highlights are:

* Unit tests for Solar_Base, _Cache, _Error, and _Locale

* End-user documentation (not just API docs) for those same classes, plus the overarching Solar class itself

I guess it’s been a productive few days. 🙂

UPDATE (2005-06-29): Looks like there may be some weirdness with the channel server; you might have to install from the tarball (pear install instead.

UPDATE 2: Solution is to issue “pear clear-cache” if you can’t seem to get 0.5.0 to install or upgrade. Thanks to Clay Loveless, who found the solution from Greg Beaver’s website.

Solar: Documentation Binge

I’ve been working on new end-user documentation for Solar, both for the general principles (in the Main area) and for the various classes (in the Solar* areas). You can see the results of these efforts here:





One of the really nice things about using YaWiki for end-user docs is that you can very easily link to methods and properties of other classes simply by typing the name of that element. For example, typing “Solar::get()” automatically links to the page named “get()” in the “Solar” area of the wiki; similarly, typing “Solar::$config” goes to the “$config” page in the Solar area. No need to remember a complex hierarchy of pages every time you want to reference a method or property, as with (say) DocBook. 😉

To get that auto-linking behavior, I created a custom Text_Wiki rule based on the default Interwiki rule. In that custom rule, all I did was edit the regular expression to accept double-colons as the area/page separator. Then I told YaWiki, via the config file, that custom rules were in a specific directory. Voila: auto-linking of class-named areas with pages names for methods and properties.

So, who says wikis are not for documentation? 😉

Solar 0.4.0

My earlier statement that I would be concentrating on administrative tasks notwithstanding 😉 I just released Solar 0.4.0 a few minutes ago. This is because the documentation process has allowed me to discover some inconsistencies and other issues.

A few highlights about this release:

* Thanks to Clay Loveless, who set up the packaging-script to use Greg Beaver‘s PackageFileManager2. This makes us more forward-compatible with upcoming PEAR releases.

* Thanks to Dan Cain, who pointed out that double-underscores in names are reserved for core PHP functionality, so I’ve changed the __solar() hook method to just solar() instead.

* Thanks to Travis Swicegood, Matthew Weier O’Phinney, et. al. for pointing out that the general $config property made more sense as a protected, rather than public, property. In most cases those options never got changed after instantiation; in the few cases where a $config option is allowed to be modified, I have added getter and setter methods.

* Thanks to Jason Sweat for hounding me earlier this year about unit testing. I have added a .phpt unit test set for Solar_Cache_File. Seeing as this one test set has already made my life much easier, there will be more coming for other parts of Solar.

For the whole list, just read the change log at our channel server. (Yes, the CSS is still ugly, sorry.)

Solar is a simple object library and application repository for E_STRICT PHP5 in the mode of PEAR, Horde, and other similar frameworks.

UPDATE (2005-06-28): There is new end-user documentation as well as a new 0.5.0 release.

Solar 0.3.0 released

I released Solar 0.3.0 on May 30 (the change log is gigantic), but didn’t want to blog about it until I had some more non-code work completed. That work has begun, and I’m satisfied enough with it to talk about it publicly now.

In short, we have a PEAR channel thanks to Clay Loveless, a complete site re-do using YaWiki (with a customized theme), some good example docs, a Hello World example app, and full auto-generated API docs. The next tasks, aside from fixing reported bugs, are to continue writing documentation and to start on a testing suite (hi Jason Sweat ;-).

Solar is a “Simple Object Library and Application Repository” for PHP5; please see the Solar site for full information.

Wikis **Are** For Documentation

So I’m late coming to this conversation, but better late than never, right?

Sean Coates asserts that wikis are not for documentation. I quote: “Now, don’t get me wrong. I think wikis have a purpose. I even run one for the doc-folk, but IMO, that purpose is NOT documentation.” He laments that wiki is not robust, that it’s not semantic, and that it’s not structured; to solve these issues in a wiki, he says, would be to make it more complex and effectively a lesser form of DocBook.

This stand, in my opinion, addresses the wrong problem. My basic rebuttal would be that PHP userland lacks not merely “robust” documentation, but that it lacks “almost all” documentation. The key here is not merely to improve the state of existing docs, but to get **any** docs to exist in the first place … and wikis help with this tremendously. They are not perfect, but they are a great start to get some docs out there.

This is a **long** post, so be warned. I plug Text_Wiki and YaWiki multiple times.

Continue reading