On Tue, Apr 17, 2001 at 07:21:11AM -0400, Stig Sther Bakken wrote:
> That touches upon the problem of merging documentation from PEAR
> (there actually is some, hidden in JavaDoc comments :-)...
Right. Emphasis should be placed on the important of inlined
documentation in PEAR classes.
> Should all the PEAR docs become part of the manual? Maybe only the
> PEAR packages bundled with PHP should be part of the manual? If so,
> how do we best make the rest of the PEAR docs available?
I don't think that the PHP manual should contain any PEAR
documentation (well, maybe just for the PEAR base class and some
instructions on using the 'pear' command line utility - which should
have a manpage, btw).
Instead, I think that each PEAR package should get its own
documentation. They would all be based off of the same stylesheets so
that they'd present a common appearance. These "manuals" would be
organized in an equivalent manner to the packages themselves.
Periodically, we might build a single PEAR manual that combines all of
these smaller documents into a large, consolidated reference.
> The PHP manual is kinda suffering from the same problem as PHP itself:
> it's huge.
Indeed.
> Is it worthwhile to try doing something about that, by splitting the
> manual up somehow?
Splitting up the manual(s) as I suggest seems like the only manageable
way to handle things, especially due to the fact that we have no way
to foresee the size of PEAR and its documentation at this point.
The only downside is the inherit difficulty in coordinating the
translation of so many smaller documents.
The advantage is that these documents can be maintained individually.
--
Jon Parise ([EMAIL PROTECTED]) . Rochester Inst. of Technology
http://www.csh.rit.edu/~jon/ : Computer Science House Member
