> >> The peardoc format will be phased out for peardoc2 which
> >> uses several files, that is one per function, one for constants,
> >> etc.
> >>
> >> It makes sense to document PECL in the pear manual since PECL is
> >> in pear.
> >
> > Well, actually this what I wanted to hear :) I also think that moving
> > PECL module's manuals to PECL is the way to go. Those extensions are
> > mostly rarely used... We can make up a list in the manual about moved
> > extensions and some text about why this happened / happens...
>
> IMO, a lot of extensions that are currently documented in the PHP
> manual could be moved to PECL and PEAR doc. This would make the
> PHP manual lighter to download, display, handle. The PHP manual
> could keep documentation about the core extensions (still to be
> defined).
This isn't really the question as we (the doc teams) don't make
these (php4/ext->pecl) decisions. I don't think anyone feels
the documentation of PECL modules belong in the php manual or
vice versa but the question is how and when to deal with the
moved extensions. When the php-dev team moves an extension we:
(a) Move the docs (phpdoc->peardoc)
Verify the docs are online in the pear manual before removed
from the php manual. (which means the peardoc vs peardoc2
craziness must also be dealt with)
(b) Make sure php.net/{extensionname} still does something
useful.
Whether filler pages or 404 handles this is in question.
And whether or not individual functions are kept track
of is another. Also, this may just refer to (c).
(c) Make a note in an up-and-coming phpdoc appendix page on
moved and removed extensions which may look like:
=============================================
| Extension | Change | Reason | Moved in |
=============================================
aspell removed pspell.. 4.3.0
cybercash removed ... 4.3.0
cybermut moved.. ... 4.3.0
---------------------------------------------
(d) ???
Ideally the php-dev team can provide a timeline for (some) future
moves and/or discuss each extension in detail and make a decision.
Maybe all moves have been completed?. For now, we rely on NEWS
entries.
Most of the above applies to removed extensions too except they
won't go into peardoc but rather remain in phpdoc for an
undisclosed (a long) amount of time. A few were removed in 4.3.0,
see NEWS and CVS entries for details. Removed/deprecated
extensions have been dealt with in a couple different ways:
(1) icap : php.net/icap simply redirects to php.net/mcal
icap docs are not generated.
(2) aspell : All deprecated functions have been listed for
quite some time. It also mentions "use pspell"
(3) Redirect to (c) above.
I prefer the second because of historical reasons and the
fact that users may still be using the old functions. For
how long will these docs remain? Should they ever go in the
appendix instead? Will this confuse users? These are good
questions :) Also, what is done may depend on the individual
extensions themselves although consistancy has its merits.
Regards,
Philip Olson
--
PHP Development Mailing List <http://www.php.net/>
To unsubscribe, visit: http://www.php.net/unsub.php
