Learning PEAR

PEAR has so much potential. I've been programming a while, I can find my way around. Even with a language I don't really know I can usually sort out what I need. Over the past month or so I've been asking what are probably trivial questions on this list, and I've received help for which I'm very grateful. But I shouldn't have to ask. The documentation for PEAR is _SO_ hard to work with - and I'm talking from the perspective of one who wants to use PEAR, not add to it. For example, I have read the section on HTML_Quickform and renderers, and looked at the example code, and I'm still not really sure what's going on. We can start with the section "Introduction - renderers", which asks the question "What are renderers?" but never answers it. The closest we get is when we learn that "The form output logic is now contained in classes that extend HTML_QuickForm_Renderer" - how does that help me? What does HTML_QuickForm_Renderer do? Then I'm told that "There are 5 renderers currently available, of which 2 are based on pre-3.0 code and 3 are new." What are their names? Where can I find out more about them? Does it matter that two are based on pre-3.0 code and, if so, how does it matter? Which of these five should I be using? How do I choose? I don't mean to pick on Quickform in particular - that's just what I have been tearing my hair out over today (and I have precious little hair to spare). As I said, PEAR has so much potential. Once one understands how to use it, it is logical and straightforward. FINDING OUT how to use it is too difficult. I don't want to have to read through and decipher lots of PHP source code just to understand how to use a facility - but I see no option. If I compare the output of "pear list-all" with the contents of the manual, most things aren't even IN the manual! The documentation that shows the API alone is NOT enough. Statements such as (HTML_QuickForm::addElement()) "If $element is a string representing an element type, then this method accepts variable number of parameters, their meaning and count depending on element type" are NOT sufficient - people just aren't going to figure out where the source file is and read it just to find out what the arguments for adding a textarea are. OK, it's easy to moan. Why aren't I helping? Well, on 28th July I posted a note including the following: "In the community spirit, I am in a position to provide some resource by setting up either a Twiki Wiki[1] or a phpBB[2] so that some documentation can be developed along these lines. My expectation is that people could contribute as little or as much as they want, and a PEAR knowledgebase / documentation / getting-started-guide / etc can be built up." I had no takers. So what's the conclusion? 1. Real programmers don't need documentation: they work it all out by reading source. 2. PEAR is well documented, Keith: you've just reached the age where you're too slow to pick it up. 3. There is possibly a documentation issue, but the people who use PEAR know how to use it so that's just fine. I remember before the big rewrite of the PHP manual. The old manual was a little quirky in places, but I taught myself PHP from it without any problem. The PHP manual today is close to the epitome of what a programming manual should look like, especially with the reader feedback. Until PEAR moves in this direction, all the excellent hard work that has been put in by the developers, documentation writers and all the other people behind the scenes isn't reaching even 5% of its potential. Most will, I suspect, just give up. This, incidentally, is the third time I have tried to get to grips with PEAR, and I was just more determined this time. All comments above meant to be constructive: I'm still prepared to help where I can. Keith