Re: RE: [PEAR-DOC] phpDocumentor tutorials/extended documentation imp lementation

LIMBOURG Arnaud wrote:

Alex is alive !! For the moment peardoc is very API oriented as i see it. No, see ie the PEAR::DB doc. The problem is, only the

maintainer of a package can really write the tutorial, i can only write the API doc based on the phpdocs. To clearify my position as editor: Note: (end-)user = programmer who wants to use a PEAR package programmer = programmer/maintainer of an PEAR package As user, the docs of the JDK or CPAN drives me often crazy. They are really API docs only. If i want to get a starting point (tutorial), i have to go Google and starting a query like "CPAN libwww tutorial". I get a lot of links to docs in txt, html, pdf, ...; some of the links are dead, some content is just unsatiesfied. After reading the tutorial and getting the idea of "how it works", i need an API doc only - but not like the JDK API docs; to much stuff: private functions etc. The same problem in the code docs of PEAR, a lot of information refers to internal stuff, nice for a programmer - senseless and dangerous for a user. While thinking about the content of the PEAR manual, i had this in mind. My idea of the PEAR Manual is: Keep information for beginners and advanced user in one place = peardoc. Tutorials are an starting point for a user, they have to be put into peardoc, because they have to be up to date and bug free as possible - no maintainer can this guarantee for "his tutorial" on a server somewhere. Also - i'm sure - the most maintainer/programmer doesn't know what is in peardoc all together, but i (should) know it as editor. I worked on the docs for XML_sql2xml; Christian wrote an really good tutorial - but it is placed on his server. And it covers information, which are desrcibed already in the PEAR Manual (installation etc.) - uninteresting if your are already familar with PEAR. As editor , i can drop such section and replace them with links to the section covering this topics in detail; advanced PEAR user can ignore this. They are not forced to read well knowed stuff. And for API doc issue - do not confound PHPDoc API doc with Manual API Doc. The API doc in the manual should only show the public interface of an package. It should give a user the information which function he can use and how to use - not how the package is implemented. Compare the API entries of the Manual with the API doc entries - they differ in the most cases. If you are a programmmer, you have to run phpdoc(-umentator) over the source, the manual will not be a replacement for this. Ok, a long mail, written in short time, but hopefully you get i idea of my thoughts. PS: i'm not against the @tutorial tag, but strictly against using it in PEAR.