> Continuing on this long on-hold thread, it would be nice to come up with > a structure to move the files into. phpdoc/en/zendapi might not be a > good idea after all, since this is supposed to be a start of a > developers manual (which will hopefully get updated eventually :). So > the streams docs should also go in here. > > What about: > > phpdoc/en/internals/zendapi > > and > > phpdoc/en/internals/streams > > for now :) And still bundling the ZendAPI docs and the Streams docs with > the manual, but in the same <part> (until something better comes > around). The ZendAPI XML files, figures and the streams XML files should > be easy to relocate. Systems people hinted that we should just do "cvs > remove" and "cvs add" since these files have nearly no practical > history. But the hanging question remains. What to do with the code > examples in ZendAPI? I mean: > > http://cvs.php.net/ZendAPI/source/ > > Any ideas? After these are handled, the remaing files (DTD, build > system) in ZendAPI are just old crap, so if we have the content in > phpdoc, the ZendAPI module can be removed entirely.
I don't know the internals of PHP very well but we should plan for future versions. How will internals/zendapi evolve for PHP 5,6...? Meaning, will this name remain appropriate? How will PHP 5 changes be handled? Regardless, this move is much needed. The phpdevel (Extending PHP 3) section would need a new name too, something involving the number 3 :) I don't know the value of ZendAPI/source/ examples or how fully applicatable they are today but they can be updated and folded into the manual in <screen> or CDATA. New examples, IMHO, should involve PECL_Gen. One interesting point. PECL_Gen is a PECL extension so I assume will be documented like any other extension or perhaps it should simply be documented in the internals section. Hmm... Maybe include a download of all examples somewhere too. As long as we're at it, the README files that live in php-src also need to find a place in the manual. And maybe, just maybe, these README files can be generated much like INSTALL/install.txt are today. This would also encourage internals folk to keep this information up-to-date. I know of two (current) article series that involve PHP internals. Maybe these kind souls can head up this internals documentation effort! :) One is our very own Sara[1] and another by Nick Loeve[2]. That would be nice! :) Regards, Philip Both part one of a series: [1] http://www.zend.com/php/internals/extension-writing1.php [2] http://www.trickie.org/code/zend_engine_one/
