Re: phpdoc / docbook / PEAR

On Fri Aug 16, 2002 at 10:1323AM +0200, Gabor Hojtsy wrote: > First of all I really interested in all tools useable with PHPDoc > (including PEAR::PHPDoc and PHPDocumentor). Sometime lately there > were some discussions on merging these two projects into PEAR > (something like the PEAR::DB and Metabase merger) or replacing the > PEAR one completely with PHPDocumentor. I thought this would be a > good move, but was never done... I think PHPDocumentor is superior > in many aspects, and it's especially good to read English > documentation about it ;)) Derick lately applied some patches to PHPDoc and he even rolled a beta release, so the project does not seem to be completely dead ;). Once someone wrote that PHPDoc is superior to PHPDocumentor in some areas (IIRC it was the parsing stuff), so we should consider merging both instead of kicking PHPDoc. Anyways, I think this decision is over to the maintainers of both packages. > Documenting your PHP code with PHPDoc and DocBook XML > > The second one connects me here ;)) What I would like to do actually > is to document the application developed for the first session and > thus present a "real life situation" example on how PHPDoc and DocBook > can be used side-by-side to document API details and concepts. As my > session description shows I would like to present a script which > converts PHPDoc comments to DocBook, so you can have one central > documentation for your concepts and your API in DocBook XML, and then > you can generate HTML/PDF/RTF with the usual tools from it. We had some discussion here about using API documentation as enduser documentation and we came to the conclusion that API documentation is often not very well-suited for this task, because it describes technical details about the package. End-users need lightning guides, tutorials and easy to understand examples that tell them how to use the package. Anyways, this shall not prevent you and others from creating such a system. -- - Martin Martin Jansen http://martinjansen.com/