I think we should give consideration to how Perl and CPAN handle things, but
with our own enhancements. Namely, we very much need a standardized core
set of PEAR libraries that are "official". These are semi-guaranteed to
have proper documentation in the phpdoc tree and are either distributed with
the core php sources as a separate piece or are packaged together as the
official PEAR distribution. That way, any authors can safely rely on a
certain PEAR library to be available if their prerequisite is to have the
core PEAR distribution installed on the server. These PEAR libraries should
also be available as separate packages for those who do not wish to install
the core PEAR distribution.
Also, there needs to be certain standards for a PEAR class/library to be
accepted into the core PEAR distribution. 1) Was it an original PHP 4
extension? 2) Does it perform some widely used function such as zlib? i.e.
The DB extraction class would be included but no database dependent layers
would be included except for maybe DBM since it's available on most unix
systems. 3) Does it absolutely meet all requirements to be a PEAR class
(proper documentation, proper coding standards, proper javadoc class and
method documentation, etc.)
As far as the documentation that's presented at php.net/manual/, I think
that the documentation of the core PEAR distribution should most definitely
be part of the PHP documentation, but separated to make it easier to peruse.
I can't answer any questions about how feasible this is using docbook but
it's probably the best way to go in the end. Documentation of independent
non core-PEAR classes should not be included in the main documentation, but
should be available somewhere else, (pear.php.net) very similar as to how
CPAN does it.
There are some random thoughts.. pick it apart as you like,
Daniel Beckham
----- Original Message -----
From: "Stig Sæther Bakken" <[EMAIL PROTECTED]>
To: <[EMAIL PROTECTED]>
Sent: Tuesday, April 17, 2001 6:21 AM
Subject: [PHP-DOC] bunch of thought
> Here's a bunch of thoughts and questions around PEAR and PHP 4.1. Any
> input is much appreciated.
>
> On php-dev we're trying to get together a plan for PHP 4.1 now. One
> of the things we want to do is to take most extensions out of the PHP
> distribution itself and make them available for example though PEAR.
>
> That touches upon the problem of merging documentation from PEAR
> (there actually is some, hidden in JavaDoc comments :-)...
>
> When PEAR and PHPDoc finally get to the point where you can easily
> generate DocBook reference docs, how should we deal with that?
>
> Should all the PEAR docs become part of the manual? Maybe only the
> PEAR packages bundled with PHP should be part of the manual? If so,
> how do we best make the rest of the PEAR docs available?
>
> The PHP manual is kinda suffering from the same problem as PHP itself:
> it's huge.
>
> Is it worthwhile to try doing something about that, by splitting the
> manual up somehow?
>
> Can we do a clean modularizing within the DocBook framework?
>
> What difficulties could splitting cause to translations?
>
> - Stig
>
> --
> Stig Sæther Bakken <[EMAIL PROTECTED]>
> Fast Search & Transfer ASA, Trondheim, Norway
>
