Forum OpenACS Q&A: Re: Greenpeace: Pay up!

I also have to wonder why Tom's claiming that NO documentation exists, when clearly some does.

Tom, I encourage you to read that and to make specific critiques as to which parts are unclear and which parts are confusing to you. That would be far more productive than making the false statement that "it has no documentation".

Sadly it's not been kept entirely up to date and revisiting this is something I'd like to do ... and perhaps if I were to insist that folks who add extensions to my previously pristine code (yeah, right) not do so unless they change the documentation, too, we'd see fewer extensions! Hmmm....

Anyway, yes, this is a basic explanation of the proc but it was 100% accurate when I lifted it from Greenpeace and put it in the toolkit (again, after discussing whether or not folks wanted it in the toolkit.)

And Jon Griffin has written additional documentation. I answered questions, and Jon wrote. I liked that approach because people who write code are often blind to which bits will appear confusing to others. Jon was sufficiently confused that he asked good questions that wouldn't've occured to me, as author of the code. If you feel Jon's document's not helpful, insufficiently clear, etc I'm sure Jon will welcome specific suggestions for improvements.

So far what's clear to me is most folks are thoroughly confused by the form builder's date type and I have to admit that I am, too. When we inherited ACS 4.2, the date type wasn't working and wasn't fully implemented. I finished it up to a minimum level and left it. It needs a lot of work, and needs documentation.

But ... the problems folks run into with the date datatype are there to confuse you if you use it when calling the form builder directly. It's truly a form builder issue.

Now ... if ad_form grows to the point where direct use of the form builder is never needed, and if we convert all packages to use it ... then I'd agree that all widget documentation etc should be gift-wrapped in a general document about ad_form, and that form builder documentation (at least the generation side, not the template tag side) be thrown out.

But currently ad_form still doesn't handle every possible case. It's not clear it ever will. Until or if it does, things like widget documentation needs to live in the form builder docs. So far no one's stepped up to the plate to document the existing form builder properly. It was poorly documented before I wrote ad_form. It's poorly documented now. Feel free to volunteer to grok the form builder widgets and to document them. Don't throw stones at me or Greenpeace over this, though, because I DIDN'T WRITE THE FORM BUILDER!!!!!