Re: Publishing API documentation for each release

Stefan Neufeind wrote:

On 8 Mar 2004 at 18:30, Daniel Convissor wrote:

On Tue, Mar 09, 2004 at 12:13:32AM +0100, Stefan Neufeind wrote:

But using HTML directly is imho not a good solution, since HTML is not well structured at all. I'm against using plain HTML for the whole doc (at the moment) ...

For the main documentation, I agree. For the docs generated directly from package source code using phpDocumentor, I agree with Martin, HTML only output is just fine.

So you want to split off all package-docs from the manual? I don't think this is a good idea either. Imho the idea of the manual was to provide a common and full view on PEAR. And if anybody intends to download the full PDF and print it out as a book that's fine with me. I must admit that when I started using PHP I also printed out a complete API-doc to have it at hand whenever I need it :-)) We should also not devide between "real docs" and "phpDocumentor docs from source" since I see that many phpdoc-documentations are improving lately and it's possible to write very good docs with a common and clear structure using that tool.

I don't see these docs being very important and spending a lot of effort converting them to other formats doesn't seem worth it. If users want other formats for the API docs, they're free to run phpDocumentor on the source files whenever they want. Similarly, if the PEAR team wants to produce other formats, we should use phpDocumentor to do that direclty rather than trying to massage phpDocumentor's docbook output.

Were do you want to generate that output from? Directly from CVS, nightly, using phpDocumentor on the server? I don't think that's a good idea, and that's why I like the current fact that we have an intermediate format. I don't mind if it's docbook or anything, but it should be well structured and provide enough details so we can cleanly transfer to any other format. Stefan Speaking for those of us working on phpDocumentor supporting peardoc2 isn't that big of deal.

Since the rest of the php manuals are in docbook it makes sense for the PEAR manual to be in docbook as well. Now if you don't want the extra work of generating and testing docbook xml to get all the basic api's, in the manual it might make sense to have a phpDocumentor html docs sitting someplace as well. Our main goal is to have people write all their docs in phpDocumentor (inline or in external tutorial files) no matter what the output. I think this provides the author a lot of flexibility and allows you to link to your inline api docs in a flexible way. Actually if people want to write extended docs in a format besides docbook phpDocumentor might be the place to look. A structured text tutorial parser should be possible to integrate, and phpDocumentor already knows howto output peardoc2 xml. anyhow if there are problems wiht the docbook output from phpDocumentor, the thing to do isn't to stop using docbook its to fix the bugs. -josh