On May 8, 2007, at 2:59 PM, Philip Olson wrote:
>> Hi all, just wanted to give you a heads-up that I'm still working
>> on this project; it took me awhile to get the tools properly set
>> up, but I'm plugging away at DocBook XML now, and I'll have a few
>> patches to send in soon, I think. Thanks for all the advice so far!
> Hello Gwynne,
>
> This is excellent news, and feel free to write the doc list if you
> have any questions and/or the IRC channels on efnet (#php.pecl and
> #php.doc). As far as information on the topic goes, let's start a
> list of the current landscape (with ideas to steal from):
>
> - The official docs: http://php.net/manual/internals
> - CodeGen_PECL: http://pear.php.net/package/codegen_pecl
> - A few tutorials: http://devzone.zend.com/public/view/tag/extension
> - The book: Extending and Embedding PHP by Sara Golemon
> - Many README files in php-src: http://cvs.php.net/viewvc.cgi/php-src/
> - A few talks: http://talks.php.net/index.php/Internals
> - A nice talk: http://netevil.org/talks/furlong-golemon-extending-
> php.pdf
> - More talks: http://talks.somabo.de/
> - A nice talk: http://talks.somabo.de/
> 200610_zend_conf_php_extension_development.pdf
> - A few examples: http://people.apache.org/~nabeel/php/examples/
>
> Also, let's create a FAQ section dedicated to the topic of
> extension writing.
This list of links has been extremely helpful to me, Philip; I
appreciate it a lot :). I'm embarassed to say I came down with a bit
of writer's block lately, so I don't have any patches to send in yet,
unfortunately. However, I would like the opinion of the list on the
avenue I've chosen.
Basically, it's my estimation that the existing internals
documentation in the manual is not organized very well, nor lends
itself to updating with any manner of ease. The material I've been
writing is a new section dedicated to the API of ZE2, rather than
trying to consolidate all the information for ZE1 (outdated) and ZE3
(still changing almost every day). My preliminary outline for the
content looks like this (yanked out of my diffs for manual.xml.in and
subject to change):
<part id="internals2">
<title>&Internals2;</title>
&internals2.intro;
&internals2.buildsys.index; <!-- configure options, ext_skel,
config.m4, config.w32, static vs dynamic builds -->
&internals2.structure.index; <!-- ext_skel, module structure,
globals, lifecycle, tests -->
&internals2.memory.index; <!-- management, persistence, TSRM -->
&internals2.variables.index; <!-- zval, hashtable, references,
constants -->
&internals2.functions.index; <!-- defining, arguments, return
values, passthru, aliasing -->
&internals2.objects.index; <!-- classes, inheritance,
properties, methods, method-function mapping -->
&internals2.resources.index; <!-- defining, creating, retrieving,
destroying -->
&internals2.ini.index; <!-- defining, retrieving, changing -->
&internals2.streams.index; <!-- using, wrappers, contexts,
filters -->
<!-- grab the PDO section from &Internals; here? -->
&internals2.apiref.index; <!-- full index of all APIs,
constants, macros, etc. -->
&internals2.ze1.index; <!-- quick list of major
differences, short discussion re: OOP -->
&internals2.ze3.index; <!-- quick discussion of major
changes, some details on Unicode -->
</part>
My thinking is to document ZE2 completely, since the differences
between 1 and 2 are small enough for the existing internals section
to be of use to anyone writing for 1, and 3 can be more fully
documented later (something I'm willing to take on as well).
If I'm given a thumbs-down on this way of doing things, I'll take the
material I've written already and use it to update the existing
internals section, but I think this method has the best chance of
giving people the truly comprehensive online reference we've lacked
for extension writing up to this point.
-- Gwynne, Daughter of the Code
"This whole world is an asylum for the incurable."
