> >> 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