Re: Real documentation?

Chuck Hagenbuch wrote: > > Quoting Richard Heyes <richard.heyes@heyes-computing.net>: > > > Does anyone have any interest in including real documentation in PEAR? ie. > > Hand typed examples and instructions on usage? These could go in the class > > files themselves, or maybe a similar named file as the class, eg > > Mail/sendmail.txt, Mail/RFC822.txt, Mail/smtp.txt etc. > > I think it's a bad idea to put them in the class files themselves. I think the > right way to go is a seperate documentation directory for each package, > personally, but seperate files wouldn't bug me if that was the consensus. > I recently proposed a central "doc" dir where packages documentation are installed separatly in the form: doc/<package_name-release>/. In your package simply create a dir called "doc" and mark it as Role="doc": <FileList> <Dir Name="/" Role="php"> <File>Mail.php</File> <Dir Name="Mail"> <File>sendmail.php</File> <Dir Name="doc" Role="doc"> <File>examples_sendmail.php</File> </Dir> </Dir> </Dir> </FileList> The installer could be easily modified to install all the 'Role="doc"' files under PEAR_DOC_DIR/mail-1.2/ (PEAR_DOC_DIR is a new php constant). This new constant or something similiar (PHP_DATA_DIR/peardocs?) is needed because we probably don't want to have all the docs and examples under the include_path. Until we have the package distrib system up, docs from packages inside the php4 module could be published in pear.php.net. I can do the modifications to the installer but need some feedback :-) Tomas V.V.Cox