Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:29824
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain wanderingknights.org from 208.97.132.81 cause and error)
Mime-Version: 1.0 (Apple Message framework v752.3)
In-Reply-To: <4850AC0C-7268-4CE2-A192-771F459A2CB5@roshambo.org>
References: <97180F0D-CB4C-4071-A859-38059C0DD1FF@wanderingknights.org> <Pine.LNX.4.62.0704252131190.1454@localhost> <0DFF3A59-3419-4A25-B907-E0E71FD41360@wanderingknights.org> <462FD093.90402@zend.com> <C74FB334-3BAF-4324-A439-235723F2EB3A@wanderingknights.org> <462FDB7B.8000907@zend.com> <8F6E78F4-9B53-43FA-8E7E-3460800F9AAD@wanderingknights.org> <4850AC0C-7268-4CE2-A192-771F459A2CB5@roshambo.org>
Content-Type: text/plain; charset=US-ASCII; delsp=yes; format=flowed
Message-ID: <8EEF96C5-7565-4D36-9894-788AD45A4C7D@wanderingknights.org>
Content-Transfer-Encoding: 7bit
Date: Sun, 27 May 2007 00:58:31 -0400
To: internals@lists.php.net
Subject: Re: [PHP-DEV] Documenting the Zend2 extension API
From: gwynne@wanderingknights.org (Gwynne Raskind)

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."