Re: "waldschrotts guide to nifty references" - manualpage draft, version 0.9b

Stanislav Malyshev wrote: > > SM>>> What for? Refcounting is not visible from userspace in no way, > SM>>> why do you need it in the manual? > > AL>> It´s an interesting fact for switchers and experts, > AL>> I don´t think it´s a good idea to hide all technical details, > AL>> we´re open source so why we´re closed technology > > It's not closed. But not everything belongs to the manual. We should not > bloat it with unnecessary details. Manual should serve it's purpose, > not try to be jack-of-all-trades. > > SM>>> Calling existing PHP manual "few" is a huge underestimate, IMO. > SM>>> But let's not bring there everything and the kitchen sink. Manual > SM>>> should be just reference, not all-about-the-subject tutorial. > > AL>> You just said. It´s reference ;) > AL>> reference for technical details IMHO, a manual should contain as much > AL>> useful information as possible > > No. We could put there description of Zend API, details of Zend memory > manager, API of zend hashes and 1001 things - but they *do not belong > there*. It's a PHP manual, and this has nothing to do with PHP as a > language. There are 1000 other places (books, Zend.com, php.net, > phpwizard.com) where PHP articles and details are due. Manual is not only > place to put PHP/Zend material, and it should be kept clean. Not as much > information as possible, but exaclty as much information as needed for a > reference guide (as opposed to a tutorial, programmer's guide and user's > guide). (crossposted to phpdoc as it might be of interest for the documenters/ translators too) just two points from my own experience: 1) finding information about internals, esp. extension interface to both php core and Zend is not easy (yet), even if you have access to all the books around and i would welcome a manual part dedicated to this special topic 2) as long as we do not have seperate tutorial and programmers and users guide and reference but only the one and only manual it should contain as much information as possible as looking through the 1000 other places will almost always end up in looking at 999 of them and missing the one you really needed putting as much as possible into the manual won't harm as long as we manage to keep it devided in clear parts and sections ok, it would lead into having even more pages, but with the ~1000 pages we have right now (print version) i don't think theres anybody out there printing it in total anyway, whoever wants to have printed material will select the parts he really needs and it would lead in longer xml translation times as the current build system is not able to do incremental builds but that is another story -- Harmut Holzgraefe hartmut@six.de