> On Fri, 29 Nov 2002, Wez Furlong wrote:
> IMO, the manual should include all of the "maintstream" PHP extensions.
> The reasoning is that if someone downloads the PHP manual, they expect
> to get the PHP manual and not have to hunt around for docs on extensions
> X, Y, Z.
So "mainstream" is defined as which are bundled with the
PHP4 source, whether it's in PECL or not? Does anyone
know or have a list of what will go where and when? Is
the install, configure, and use process different for
PECL extensions? Why are any PECL extensions bundled in
PHP4 source? That seems to defeat the purpose.
Currently the php and pear docs are like separate entities,
perhaps we should tie them closer together. Like,
download-docs.php can include versions with the pear manual.
And php.net/{pearextension} can either redirect to or
load appropriate manual/info pages. Anyway, point is
they can be better and closer friends.
> Remember that one of our goals is to move most of ext/* into PECL, but
> still bundle these pickled extensions in our official release packages,
> so the idea that PECL should be documented under PEAR is not such a good
> one.
I'm not familiar with this topic. Currently PECL is documented
under PEAR, and since it's part of PEAR it makes sense. It's
hard enough to decide which extensions go into PECL let alone
which PECL are documented in what manual. I am curious what is
meant by "most", that sounds a little scary and makes having
all extensions in one manual more attractive. Is there an
option to only download needed pecl at compile time, kinda
like how 'pear install foo' is done now? Or an option to
download each separate, or all of them at once? I don't see
why any PECL would be bundled. But anyway, back to the docs.
Some disadvantages of having the docs separate:
* phpdoc has a ton more translators.
* more people have phpdoc karma and feel comfortable
touching phpdoc source
* downloading two manuals and/or viewing two websites
* "most" living in pecl, yet many bundled in php4
With the main advantage being it would be in its proper home.
> Again, IMO, the madness of having no less than 3 different docu systems
> (phpdoc, peardoc and peardoc2) makes very little sense; why not just use
> "one system (tm)" for docs? (let's save some developer brain power for
> more useful things).
The peardoc/peardoc2 issue is temporary and confusing but will
be remedied at some point, not sure when. In fact, I personally
don't document pear because of it. The matter of a completely
separate PECL manual I also disagree with. Although who knows,
maybe if the build processes were more closely done together it
wouldn't be so bad.
> So, what I'd like to see (and this seems reasonable, IMO) is:
>
> o One doc download for the PHP core + bundled extensions (which may
> reside in PECL).
> o One doc download for the PEAR classes + non-bundled PECL extensions
> o One doc download for extension developers (the streams and zend API
> stuff needs a proper home).
> o One doc system to rule them all (but keep it modular of course).
I agree with this except have reservations about some PECL
going in PEAR manual while others in the main manual. I
*strongly* agree with a uniform system but AFAICT it won't
exactly be the case with current plans (phpdocumentor).
Regarding the separate developers manual, the main reason it
hasn't already been done (aside from time constraints) is there
is question on whether it should be translated or not. I vote no
it shouldn't as that'd mean outdated developer docs as the zendapi
stuff seems to change a lot and translations are slow and
sometimes are just one-time operations. In fact, aren't the current
en zendapi docs already outdated? I don't know this topic. On a
related note, those PHP4/README.* docs would fit nicely in this
dev manual.
Regards,
Philip
--
PHP Development Mailing List <http://www.php.net/>
To unsubscribe, visit: http://www.php.net/unsub.php
