PHP PEAR Questions and Answers - Re: [PEAR-QA] Package Abstracts

Author

Re: [PEAR-QA] Package Abstracts

Martin Jansen

2004-11-18, 8:56 pm

On Tue Nov 16, 2004 at 09:2624AM +0100, Aaron Wormus wrote:
> After manning the booth at our LinuxWorld stand and spending a good
> amount of time hanging around the booth at IPC2k4, I would like to
> propose that we create a simple format of the "mini-documentation" of
> EACH package.
>
> This documentation would not be comprehensive, but would be well written
> and provide an overview of what each package does. A good example is
> Perl's documentation which requires the following 5 sections:
>
> Name
> Abstract
> Synopsis
> Description
> Notes and Bugs
>
> I would propose that this documentation be maintained along with the
> packages, and updated to be included and installed in the docs/ folder
> with each release.

What do you think of making the mini documentation part of package.xml?
Basically <summary /> and <desc /> already do the job of "Abstract" and
"Description" these days, and Greg is working on a new XML layout
anyway.

--
- Martin Martin Jansen
http://martinjansen.com/

Aaron Wormus

2004-11-18, 8:56 pm

Martin Jansen wrote:

>What do you think of making the mini documentation part of package.xml?
>Basically <summary /> and <desc /> already do the job of "Abstract" and
>"Description" these days, and Greg is working on a new XML layout
>anyway.
>
That would really be the best. The reason why I brought this topic up is
that no documentation gets installed on the client computer. If the
installer could generate simple linked html pages which lists the
packages which are installed and gives some information about them
(information that's in the package.xml file, link to documentation, etc)
it would make PEAR a lot more userfriendly IMO.

Under Windows the installer could even create an item in their start menu...

Aaron

Daniel Convissor

2004-11-20, 3:55 pm

On Thu, Nov 18, 2004 at 10:37:12PM +0100, Aaron Wormus wrote:
> That would really be the best. The reason why I brought this topic up
> is that no documentation gets installed on the client computer

How about the command "pear info DB"? While not a complete set of
documentation, it exists now and provides the basic overview of the
package.

--Dan

--
T H E A N A L Y S I S A N D S O L U T I O N S C O M P A N Y
data intensive web and database programming
http://www.AnalysisAndSolutions.com/
4015 7th Ave #4, Brooklyn NY 11232 v: 718-854-0335 f: 718-854-0409

Greg Beaver

2004-11-22, 3:57 am

Martin Jansen wrote:
> On Tue Nov 16, 2004 at 09:2624AM +0100, Aaron Wormus wrote:
>
>
>
> What do you think of making the mini documentation part of package.xml?
> Basically <summary /> and <desc /> already do the job of "Abstract" and
> "Description" these days, and Greg is working on a new XML layout
> anyway.

Please decide this quickly :) any additional changes to package.xml
better be worth my time in both implementing and unit-testing. I want
to release 1.4.0a1 by mid-December.

Thanks,
Greg

Greg

Sponsored Links