Hello everyone!
In reference to Mehdi's concerns[1] about the APD docs I'm writing
this in regards to all PECL documentation within the PHP Manual. The
method for documenting PECL extensions is unknown right now so let's
sit down and solve this problem. Here are a few points, I'm sure
there are more:
---
(a) Dealing with PHP version information
Since a version of PHP will have an unknown version of the PECL
extension installed, we can't really relate the two. Or, can we?
Should we create a functable[2], of sorts, for PECL extensions? The
version information for a function might for example say: "(PECL >=
0.4.2)" -- This smells like a large task, and functable is a beast
with few able to tame it.
For removed functions it appears they say "no version information,
might be only in CVS" currently so that too needs handled.
(b) PECL extensions that come bundled with PHP
Given the point above, how trustworthy is this? We can't assume
people don't use "pecl upgrade ..." so a simple mention might be in
order within reference.xml, or perhaps not.
(c) PECL extensions that come enabled by default with PHP
This is important news because typically 'enabled by default
extensions' aren't explicitly disabled by sysadmins and are
statically compiled into the PHP version. People should know this
information.
(d) Linking to Windows DLL's
This recently changed (in a good way), example link: http://
pecl4win.php.net/ext.php/php_json.dll so basically we should link to
these. Or, should pecl.php.net instead link to these? Seems
appropriate since they contain all the source files and since all
PECL extension docs link to the appropriate pecl.php.net pages. We'll
need to collaborate. Example use in the docs currently:
&url.pecl.win.ext;php_json.dll
(e) What is PECL?
We are more or less forcing all PHP users to know what PECL is, but
how far should we go? A FAQ that's linked within every PECL
extension? And elsewhere, like in tutorial|about|features|???
(f) Linking to documentation
The pecl.php.net site does not link to the documentation, it should.
Should this be automated? If not, how should it be done?
---
And since more and more extensions are being moved into PECL, and at
one point in time a goal was to move almost all extensions into PECL,
this problem will only grow more and more severe. The version
information problem is the largest issue and is very much open to all
brainstorming ideas especially on the implementation side of things.
Please respond!
Regards,
Philip Olson
[1] http://news.php.net/php.doc/969374035
[2] http://cvs.php.net/viewvc.cgi/functable/
