Paul M. Jones

I just got this via email: "Congratulations on passing the Zend PHP Certification exam! " Woohoo!

But please, no applause; just throw money. ;-)

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.

The Supreme Court has just ruled that governments can seize private property under eminent domain and give that property to other private holders.

The case in question was about a developer who claimed he could generate more tax revenue for local government with a particular piece of land, except the landholder wasn't selling. The Supreme Court has effectively ruled that increased tax revenue is a legitimate point of "public interest"; as such, governments can take your property and give it to other people who promise to pay more taxes than you do.

I'm so mad I can't see straight.

UPDATE: Here's a link with a good overview from AP News MyWay.

UPDATE: Another overview from the NY Times.

Not only is Batman Begins the best film/TV Batman, it's one of the best action superhero films ever, on par with the first Superman, Spider-Man 1 and 2, and Unbreakable. Genuinely moving and powerful. I give it my highest rating: worth full evening price, twice. In fact, you will enjoy it even more on second viewing, because once you know the plot, you can concentrate on all the beautiful little details.

Please note the PG-13 rating; parts of Batman Begins are far too disturbing for little children (almost too disturbing for adults approaching middle age).

This film is exceptionally good: strong characters, solid storyline, mostly believable technology, moving soundtrack, and great performances (but for Katie Holmes, who pretty but bland and kind of weak). When Scarecrow puts the Fear on people, you get to see what they see, and it is nightmarish. The supporting cast really are "supporting" -- they're all strong in they're own right, but they know they are there to help Batman when he needs it. Brilliant writing.

And the soundtrack! It has the distinction of being the work of two distinctly different composers: James Newton Howard (e.g. Unbreakable) and Hans Zimmer (e.g. various action films and Rain Man). You can hear their different styles come through in different places, but sometimes you don't know which is which. Frankly, I never thought a two-note theme could *be* a theme ... but it is, at least when you have the underlying foundation of the rest of the composition. The first note builds, and builds, and then breaks to the second note just as an important scene element tips on-screen; it's a very powerful element, even though you may not always notice it on first viewing.

For those of us who care about this kind of thing, there are plenty of nods to Jung, and to the Sodom-and-Gomorrah story. The storyline is almost point-for-point in line with the Joseph Campbell heroic monomyth.

If you want to hear more about it, read on, but be warned: there are spoilers below.

I don't want to review the movie, exactly, but I do want to point out some highlights. Before I do, though, I want to say that you really should read "The Hero With A Thousand Faces" by Joseph Campbell.

Campbell researched a great deal of mythology and religious stories, everything from the Babylonian mythos to the Egyptians, Greek and Roman myths, Hindu, native American, northern European, Judaism, Christian, and Islam. In his research, he noticed that the same basic 15 points came up in all the "hero" stories, regardless of the time period or the geographic region. He called this the "monomyth" template.

It turns out that we're telling the same stories to each other even now: Star Wars, the Matrix, Superman, and many other sci-fi and fantasy and comic-book plots have most or all of the elements of the Campbell monomyth. Perhaps I'll write more about the monomyth in another post some time, but this overview should provide a good introduction with some good highlights from pop culture.

Now, back to Batman Begins:

The film opens with Bruce Wayne as a child of 7 or 8; he steals from his playmate Rachel an arrowhead she has found. He runs, and almost immediately plunges into a poorly covered well. In the well, there is a cave entrance, and bats flock out of it to surround the terrified boy; this is one of the traumas that leads to the origin of Batman (the other is the murder of his parents). That the film begins with an act of theft by its hero (who will go on to combat thieves), and that it leads him to the Cave of his subconscious, is clearly aspect of the Campbell monomyth and the work of Jung.

As a young man of 21 or 22, Bruce confronts his own desire to commit murder when the killer of his parents is released on parole; he does not commit the act, but only because the killer is gunned down in front of him. Rachel, now a lawyer, takes him to the underside of Gotham where he gets to see the face of true criminality; after that, he sets out on a journey to learn about the criminal mind. At the end of his seven years in the wilderness (reflections of Buddha Siddhartha), he is approached by the League of Shadows and is trained to fight evil, which he begins in earnest on the night of his 30th birthday (reflections of Christ). Again, we see points of the monomyth described by Campbell: the passing of the first veil, the descent into the underworld, the gift of special powers, and the return from the underworld to bring new knowledge.

***

Batman Begins reflects another ancient tale, that of the destruction of Sodom and Gomorrah.

In the Judeo-Christian telling, Abraham has just finished hosting two angels and the Lord at a meal when God tells Abraham that he (the Lord) is going to destroy two cities that have become evil and wicked beyond His forbearance. Abraham asks God to withhold his wrath, and bargains with Him; eventually the Lord says he won't destroy these cities, but only if Abraham is able to find ten righteous men living there. (Abraham himself never goes to the city.)

The narrative then turns to a man named Lot, who lives in Sodom. He takes in the two angels who just left Abraham. There is an altercation with the men of the town, who want to rape the messengers of the Lord. The angels tell Lot to escape the city, and then lay waste to the it before the Lord rains fire down on the whole plain (including Sodom, Gomorrah, and other towns in between).

In Batman Begins, we never see the Lord directly, but we sure do see the angels of destruction; they are the minions of Ras al Ghul, leader of the League of Shadows, who are planning the destruction of Gotham. Bruce Wayne/Batman, as a combined Abraham/Lot character, bargains for the corrupted Gotham/Gomorrah. As in the Jewish tale, the angels of the League proceed with their plans to destroy the city.

But this is where the narratives diverge: Batman, as a dark angel of salvation, stands in the way of the immediate destruction of Gotham and defeats Ras al Ghul himself, even though the League's plan partially succeeds with the release of Arkham inmates (the worst of the worst) into the city. As such, the dark Batman is the savior character, and the destroyers are a corrupted evil, a significant twist on the original Sodom and Gomorrah tale.

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.

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.

I've written about documentation before, many times, on this blog...

• http://paul-m-jones.com/blog/?p=14
• http://paul-m-jones.com/blog/?p=15
• http://paul-m-jones.com/blog/?p=16

... and on PEAR-DOC and PEAR-DEV; here are some thread links,

• http://marc.theaimsgroup.com/?t=108159655600001&r=1&w=2
• http://marc.theaimsgroup.com/?t=108179653300004&r=1&w=2

and here are some highlights from those threads:

Date: April 12, 2004 3:29:46 PM CDT
From:   pmjones@ciaweb.net
Subject: [PEAR-DOC] Re: [PEAR-DEV] Online doc generator
To:   jcastagnetto@yahoo.com
Cc:   pear-doc@lists.php.net

> > 3. Easy to learn the markup to lower barriers to entry (docs
> > are less sexy than code, let's make it easy to get into them
> > ;-)
>
> Huh? What is so difficult about XML?
>

Indeed; what is so difficult about DocBook?  Obviously something
is flawed in the current PEAR documentation system, or we would
have more docs there.


Date: April 12, 2004 3:47:06 PM CDT
From:   pmjones@ciaweb.net
Subject: Re: [PEAR-DOC] Requirements for Documentation System
To:   jmcastagnetto@php.net
Cc:   pear-doc@lists.php.net

> I am still unsure about why we need
> up-to-the-microsecond updated documentation.

For instant feedback and gratification for the documentor.  You
write code, you get to test it right away and tweak it again.
You write docs, you want to see the results right away so you can
keep tweaking; it is rewarding to the writer, and we want to
reward writers.


Date: April 13, 2004 2:36:37 PM CDT
From:   bmansion@mamasam.com
Subject: Re: [PEAR-DOC] Smashing DocBook
To:   mike@php.net, pear-doc@lists.php.net

> Sorry folks, but I really don't get the point on
> smashing DocBook per se.  If you're able to write
> plain HTML you should by no means have problems
> writing docbook XML.  I also doubt that ::^--
> reST ~~_** is that more easier... :-)

.02 of Mike

<sect1 id="mail.stupid.reply">
<title>Reply to stupid mail</title>
<para>That's not the point</para>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->


Date: April 14, 2004 1:05:34 PM CDT
From:   pmjones@ciaweb.net
Subject: Re: [PEAR-DOC] Doc help requestedd
Cc:   pear-doc@lists.php.net

Composing documentation, in general, is difficult and
not-immediately-rewarding, especially for coders who are not also
technical writers.  I argue that if there is an open, welcoming,
friendly framework already in place then it will be easier for
developers to iteratively build their documentation.  That way
the writers can concentrate on the writing, not on the system.

I bring all this up (1) to introduce some of the arguments I will make later in this post, and (2) to point out that that documentation is important to me; I place as high a value on good code as I do on good docs. My requirements for good docs are that they are written well, for end-users, in an accessible format, to address actual end-user needs. If they're in plain text, so be it; if they're in PDF, so be it.

On further consideration, it might be easier to address Coates' points one-by-one.

There is a recurring idea in the PEAR community that they'll set up a wiki and fix all of the PEARdoc problems.

The problem with PEAR-DOC is not that the docs are not structured properly; it's that the docs are *not there* to begin with (or that there are not enough, and not written well-enough). I contend it is because entry barriers to PEAR-DOC as a DocBook repository are too high, and that the reward-to-effort ratio in writing PEAR-DOC docs in DocBook is far too low.

"Don't worry," they say, "we'll write a Docbook exporter for our wiki markup."

I am of the opinion that this is simply impossible without comprimising either 1) Docbook's robustness or 2) Wiki's simplicity

Not entirely true; a slight bit of added complexity in wiki markup can have a great deal of added value. C.f. the "function" parser in the Text_Wiki package. But certainly DocBook is far more robust than wiki. However...

In (1), I think we phpdoc'ers would agree that docbook is robust. It allows very detailed parsing that allows us to generate things like PDF and CHM. It allows us to parse the document tree and determine which extensions exist, constants in said extensions, functions in said extensions, the prototypes for said functions. Docbook is primarily focused on meta-data, and while visual markup is considered in meta-data markup, docbook prefers to remain output-ignorant. Docbook is _not_ what-you-think-is-what-you-get, as Wikis often claim to be. Docbook is extremely structured, by nature.

... who cares?

Look, I just want somebody to write some docs on their project so I can read them on the web. I'm trying to do it with my projects. My wikis are output-ignorant too; take a look at Text_Wiki and YaWiki for examples. You can write any renderer you like and it'll go to that output format.

Now, I care as much about semantics as much as anyone else (again, see Text_Wiki for an example of the lengths to which I went to preserve semantic implications of markup), but once you convert it to PDF or whatever, all those happy semantics are **gone** -- those formats just don't care. So the combined arguments "DocBook is semantic and structured" and "DocBook converts to non-semantic output" are almost opposed to each other.

I'll get to the "structure" argument in a minute.

In (2), Wikis are known (and consequentially popular) for their simplicity. Anyone who's tried to create a *||Multi|Column|Table||* would agree that they're meant for simple markup only (but often have certain "complicated" functionality). Sure, it would be possible to implement wiki-specific markup for things like and &entities; but for each one, additional wiki syntax would need to be added. Once enough new syntax was added to accomplish similar goals (robust wiki->docbook conversion), you'd have a toolbox that's no simpler than docbook.

What goals, exactly, are we trying to accomplish? I just want to read me some docs about your project so I can figure out what the sam-hill is going on, and where to start.

Wikis are unstructured, by nature.

Indeed; they are as "unstructured" as the web itself, or as Google.

Here's the thing: wiki page relationships **are** structured. It's just that their structure is flat, in a peer-to-peer model. You address each one individually as a peer, not as part of a hierarchy. This can be good or bad, depending on your requirements.

In fact, one nice thing about a flat structure is that you can lay a hierarchical structure on top of it, and replace that layer at will, to make the hierarchy look like anything you want. Again, c.f. YaWiki, where you can implement a navigational hierarchy using the AreaMap page; this hierarchy can be used in your output, or not, as you see fit.

I believe that anyone who REALLY thinks this should be done has never written a <methodsynopsis> block.

Guilty on that count; I've not written many. But take a look again at Text_Wiki and the "function" parser; it has enough stuff there to satisfy most comers, I think.

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.

Docbook isn't magic; it's just XML. Once you get past the mental block of "this is hard", it really isn't.

Ah, now we get to the heart of the matter. Coates is right; XML is not hard. But:

Organizing and writing documentation in general **is** hard. Having to learn a new system, and build an environment for your documentation, and then compile your documentation, and then troubleshoot your documentation, is a barrier that needs to be lowered. Sweet merciful jebus, we don't compile our PHP code, why should we have to compile our docs?

Wikis lower this barrier dramatically. They allow a quick-and-easy, fast-feedback, high reward-to-effort ratio, iterative approach to collaborative writing. You don't even need to know the markup; you can just toss up some plain text to start and iteratively refine it as you (and others!) see fit.

For examples of what's possible with YaWiki, check out these sites. Are they perfect? No. But as you can see, the docs are there. :-)

• http://phpyawp.com/
• http://solarphp.com/
• http://wiki.ciaweb.net/
• http://nursing.memphis.edu/

Update: Tidied up the blockquotes so they wrap properly.

I went to see the DreamWorks movie Madagascar this weekend. I'd been looking forward to it for some time, if only because I like good computer animation. Unfortunately, the storyline in Madagascar is not that great; while fun for the family, it'll be more-so for the the kids than the adults. (The work put out by Pixar is much better, both technically and story-wise, and it's just as much fun for the parents as the children.)

In fact, there's one point where the zebra, voiced by Chris Rock (read into that what you wish ;-), cries out "Motherf-" and then is cut off by other conversation mid-word. While it's funny because we know Chris Rock, I found it shocking and unexpected to hear that in a kid's movie.

I'm not going to review the movie here (the IMDB link above has a fine one), but I did want to point out that my favorite parts of the film had nothing at all to do with the main characters. For example, there are these four penguins staging a break for Antarctica, and they're a lot of fun; think mobsters crossed with Special Forces. The two British monkeys, one of whom speaks only in sign language, don't get anywhere near enough screen time. The real laugh-out-loud bits come from the half-insane King Julien of the lemurs (voiced by Sacha Baron Cohen) who is by far the funniest character in the picture . Julien doesn't show up until the second half of the movie, but when he's on screen you're laughing the whole time.

In all, I'd say Madagascar is worth the matinee price, but probably more-worth it if you see it with some kids.

It's been a busy weekend playing catchup on bug reports and feature requests. These projects of mine have seen new releases yesterday and today as a result:

* Contact_Vcard_Build 1.1.1 (bugfixes)
* Contact_Vcard_Parse 1.31.0 (bugfixes)
* DB_Table 1.0.1 (bugfixes)
* Savant3 dev 4

The new Savant release bears a little talking-about. I don't like breaking backwards compatibility even in a development release if I can help it, but there was one issue that required an architectural change related to error handling. That is the removal of error-handling resources (e.g., Savant3_Error_pear, et. al.), which is pretty significant if you use it. (Exceptions are a special case; see below for more on that.)

The original purpose of having error-handling resources was so that you could report and test for errors using your own framework-specific calls. While the Savant3 error resources would allow you to plug into those systems, the number-one complaint I got was that Savant3 still returned errors as Savant3_Error objects, which meant that you had to use Savant3 to check for errors, not the framework-specific error checker. That's obviously a problem, as it doesn't meet the original goal of being able to abstract error reporting and testing.

As a result, I have removed the error-handling resource infrastructure. Instead, if you want to use framework-specific error reporting and testing, you should extend Savant3 and override the error() and isError() methods. For example, if you wanted to use PEAR_Error handling, you would do something like this:

include_once 'Savant3.php';
class Savant3_Pear extends Savant3 {

    public method error($code, $info = array(), $level = E_USER_ERROR,
        $trace = true)
    {
        if (! class_exists('PEAR_Error')) {
            include_once 'PEAR.php';
        }
        $err = PEAR::raiseError($code, $code, $info, $level);
        return $err;
    }

    public function isError($obj)
    {
        if (! class_exists('PEAR_Error')) {
            include_once 'PEAR.php';
        }
        return PEAR::isError($obj);
    }
}

The difference between this and the previous (Savant2) error handler resource architecture is that the call to error() will return a PEAR_Error, not a Savant3_Error. In addition, while you can test for errors using the extended isError() method, you can use PEAR::isError() instead because the returned error object is a real PEAR_Error object. This applies to all frameworks that use their own error handling systems (which is, well, almost all frameworks, including Solar, which now bundles Savant3 as its default template system).

Exceptions are a special case; they're native to PHP5, so they have native support in Savant3 now (instead of being an error handler resource). If you want Savant3 to throw exceptions, call setExceptions(true) and it'll throw Savant3_Exception objects when errors occur.

For full change notes, be sure to visit the Savant3 website.

Before I continue, please note that Clay Loveless volunteered the hosting services and has managed the transition in a most professional way (even though he is not a hosting provider, he's a PHP guru). Clay set up the new services, including mailing list (with transition of archives and addresses), email accounts, Subversion repository, database, web with SSL, and PEAR channel server. He runs Killersoft and Pearified; you really should consider contacting him for your next PHP project, as his attention to detail and commitment to high quality service have been obvious throughout the transition process.

And now the cat is out of the bag; everything we gained in the transition is listed above. Point by point, the details are:

* Solar is still at solarphp.com, the API docs are still at solarphp.com/api/, and bug reporting is still at solarphp.com/bugs.php.

* The Subversion repository is now available for browsing and anonymous reading at solarphp.com/svn/. You want to commit patches or add packages? Email me, the benevolent dictator of the Solar system, at pmjones at solarphp dot com -- we'll work something out.

* Clay set up a PEAR channel server based on Davey Shafik's excellent Cerebral Cortex work. Although there are no packages loaded yet, they will end up at solarphp.com/channel.php. Look for more on that later. In the mean time, you can download the latest release at http://solarphp.com/Solar-0.2.0.tgz.

Right now solarphp.com is hosted at TextDrive, which (a) costs money, and (b) is not too flexible. Through the generous good will of Clay Loveless, who runs pearified.com, Solar will soon be hosted on another machine. Among the benefits will be SSL-based access to the Subversion repository, as well an honest-to-Zoroaster PEAR channel, which means we'll be able to do some cooler stuff with installations and usage tracking.

This may entail a bit of confusion over the next few days. We'll be moving the mailing list, so you may see an "unsubscribe" and then a new "subscribe" in your inboxes. Not sure yet if that'll be necessary, but don't be surprised if it shows up. Don't know yet how to export the archives, but if we can save them, we will.

After that's done I'll post another update. The mailing list and Solar website may be flaky during transition, so if you need to contact me, use my "real" address at pmjones-at-mac-dot-com.

(p.s. Yes, PHP Tropics was excellent. I'll write more about that later. :-)