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
> > 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
> >
> >
> >
>
>
> --
> PEAR Documentation List Mailing List (http://pear.php.net/)
> To unsubscribe, visit: http://www.php.net/unsub.php
>
