Re: Publishing API documentation for each release

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