[prev in list] [next in list] [prev in thread] [next in thread] 

List:       pear-doc
Subject:    Re: [PHP-DEV] Re: Modules/Extensions not in 4.3
From:       Wez Furlong <wez () thebrainroom ! com>
Date:       2002-11-29 12:21:00
[Download RAW message or body]

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


[prev in list] [next in list] [prev in thread] [next in thread]