[PHP-DEV] Re: [PHP-DOC] Re: [PHP-DEV] Re: Modules/Extensions not in 4.3

[Derick Rethans]

On 4 Dec 2002, Stig S. Bakken wrote:

> On Fri, 2002-11-29 at 18:20, Philip Olson wrote:
> > > 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.
> 
> Not quite.  One purpose of separating the (cvs) source of PHP itself and
> extensions is to be able to pick the latest working version of
> extensions when releasing PHP, rather than waiting for extension
> maintainers to fix bugs during the PHP release process.

Right, and what if the API changed? The 'working' extensions don't even 
compile then anymore. Of course this does not happen very often, but 
it's definitely something to think about.

Derick

-- 

-
 Derick Rethans http://derickrethans.nl/ 
 PHP Magazine - PHP Magazine for Professionals   http://php-mag.net/
-


-- 
PHP Development Mailing List 
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Re: Modules/Extensions not in 4.3

[Stig S. Bakken]

On Fri, 2002-11-29 at 18:20, Philip Olson wrote:
> > 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.

Not quite.  One purpose of separating the (cvs) source of PHP itself and
extensions is to be able to pick the latest working version of
extensions when releasing PHP, rather than waiting for extension
maintainers to fix bugs during the PHP release process.

 - Stig


-- 
PHP Development Mailing List 
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Re: [PHP-DOC] Re: [PHP-DEV] Re: Modules/Extensions not in 4.3

[Arnaud Limbourg]

> We talkes about this at our March Doc meeting. The problem is that the
> different doc systems mostly started out from the initial "phpdoc"
> repositories system, and developed on their own ways. Reuniting the build
> systems under one umbrella would be quite a hard task, and I don't know who
> can volunteer on this. It obviously needs more then one person from every
> doc team, who understands the system used there, and can work to unite
> them. In March, the central build system for all php documentation project
> seemed to be a faraway dream...
> 
> Well, it also needs to be mentioned, that if you look at the different
> parts (php-dev, pear-dev) they also have different coding standards, CVS
> rules, etc.), so it's still a trouble for developers.

Indeed, this would be huge task. Plus, is having a big doc system  better than two 
smaller units ?

There is already a lot of work to move from peardoc to peardoc2.

> Well, I think we had a wrong picture about PECL (or at least I had),
> that the PECL extensions were distributed separately. If all the
> extensions are in PECL, the manual should contain the core ones,
> bundled with PHP, that's for sure.
> 
> We would also like to gain some on moving docs to PEAR/PECL doc tree
> as there will be less to translate for the core PHP manual. I don't
> think so that any translation team can handle the current size of the
> manual and keep it up to date. Some translations had backed off when
> faced the size of the work to do to make the translation complete, or
> manage a translation at some stage. From an insider view, I can say
> that the Hungarian translation also faces such problems now, we are
> unable to at least keep the translation up to date...

-- 
PHP Development Mailing List 
To unsubscribe, visit: http://www.php.net/unsub.php

[PHP-DEV] Re: [PHP-DOC] Re: [PHP-DEV] Re: Modules/Extensions not in 4.3

[Gabor Hojtsy]

Well, you raise some points ;)

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

We talkes about this at our March Doc meeting. The problem is that the
different doc systems mostly started out from the initial "phpdoc"
repositories system, and developed on their own ways. Reuniting the build
systems under one umbrella would be quite a hard task, and I don't know who
can volunteer on this. It obviously needs more then one person from every
doc team, who understands the system used there, and can work to unite
them. In March, the central build system for all php documentation project
seemed to be a faraway dream...

Well, it also needs to be mentioned, that if you look at the different
parts (php-dev, pear-dev) they also have different coding standards, CVS
rules, etc.), so it's still a trouble for developers.

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

Well, I think we had a wrong picture about PECL (or at least I had),
that the PECL extensions were distributed separately. If all the
extensions are in PECL, the manual should contain the core ones,
bundled with PHP, that's for sure.

We would also like to gain some on moving docs to PEAR/PECL doc tree
as there will be less to translate for the core PHP manual. I don't
think so that any translation team can handle the current size of the
manual and keep it up to date. Some translations had backed off when
faced the size of the work to do to make the translation complete, or
manage a translation at some stage. From an insider view, I can say
that the Hungarian translation also faces such problems now, we are
unable to at least keep the translation up to date...

Goba



-- 
PHP Development Mailing List 
To unsubscribe, visit: http://www.php.net/unsub.php

[PHP-DEV] Re: Modules/Extensions not in 4.3

[Wez Furlong]

Hi Philip,

On Fri, 29 Nov 2002, Philip Olson wrote:

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

As I just explained to you on IRC (and repeating here "for the record"),
the aim is to have a virtually empty php5/ext/ directory and have all
extensions (besides standard) living in PECL.
Once in PECL, the extensions gain dependency tracking information.

When we publish a release, we will pick the "gold" extensions based on
the userbase (popular extensions will be included by default) and the
level of maintenance (crufty extensions might not be bundled by
default).

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

Yes, the developer docs should be written only in english for the
reasons you mention above (which are similar to the reasons for not
localizing the php error messages).

--Wez.


-- 
PHP Development Mailing List 
To unsubscribe, visit: http://www.php.net/unsub.php

[PHP-DEV] Re: Modules/Extensions not in 4.3

[Philip Olson]

> 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 
To unsubscribe, visit: http://www.php.net/unsub.php

[PHP-DEV] RE: [PEAR-DOC] Re: [PHP-DEV] Re: Modules/Extensions not in 4.3

[LIMBOURG Arnaud]

Well, you suggestion makes sense. I wonder about something though. How
different are phpdoc/peardoc/peardoc2 ?

As i said the plan was to move from peardoc to peardoc2. If we move
everything to phpdoc we'll have to port peardoc and peardoc2 to phpdoc, it
will need a lot of work.

There is also a project to generate peardoc2 automoatically from PHPDoc
comments using phpdocumentor and others scripts, greg beaver as well as
alexander are working on that. If peardoc2 and phpdoc are compatible that
would be great.

Arnaud.


> 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.
> 
> 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.
> 
> 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).
> 
> 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).
> 
> --Wez.
> 
> On Fri, 29 Nov 2002, Philip Olson wrote:
> 
> > > >> 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
> >cybercashremoved  ...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 th

Re: [PHP-DEV] Re: Modules/Extensions not in 4.3

[Sebastian Nohn]

Wez Furlong schrieb:

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

+1

Regards, Sebastian Nohn
-- 
[EMAIL PROTECTED] - http://nohn.net/

-- 
PHP Development Mailing List 
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Re: Modules/Extensions not in 4.3

[Wez Furlong]

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.

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.

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

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

--Wez.

On Fri, 29 Nov 2002, Philip Olson wrote:

> > >> 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
>cybercashremoved  ...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 
> To unsubscribe, visit: http://www.php.net/unsub.php
>
>
>


-- 
PHP Development Mailing List 
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Re: Modules/Extensions not in 4.3

[Marcus Börger]

ext/db is deprecated by dba since 4.3 (earlier versions of dba are very 
different).
I plan on emulating db calls in ext/dba. If this is done we can either 
remove db
or move it to pecl (i vote for removing then). The remaining difference 
current
difference between the two is that db uses magic quotes for key names while
dba does not. I plan to make the wrapper functions in dba work exactly the 
same
way as in db.

If you want to do something about those two extensions now you could simply
add a note to every db page that db is deprecated and also add a link to the
corresponding dba functions.

regards
marcus

At 11:57 29.11.2002, Philip Olson wrote:
> >> 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
   cybercashremoved  ...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 
To unsubscribe, visit: http://www.php.net/unsub.php



--
PHP Development Mailing List 
To unsubscribe, visit: http://www.php.net/unsub.php

[PHP-DEV] Re: Modules/Extensions not in 4.3

[Philip Olson]

> >> 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
   cybercashremoved  ...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 
To unsubscribe, visit: http://www.php.net/unsub.php