Re: Publishing API documentation for each release

On 8 Mar 2004 at 20:30, Martin Jansen wrote: > On Mon Feb 16, 2004 at 10:3726AM +0100, Martin Jansen wrote: > > On Sun Feb 01, 2004 at 12:2615PM +0100, Martin Jansen wrote: > > > over the weekend, I have been toying around with the idea of > > > generating human-reabable formats for the API documentation of > > > each release and publishing them as independent manuals (detached > > > from the existing PEAR manual.) > > > > > > > FYI: I haven't lost sight of that, but the harddisk of the machine > > where that stuff is located atm is suffering from (partial) physical > > damage, which makes it kinda hard to work with. > > > > As soon as the replacement disk is in place, there should be some > > progress again. > > I have been playing around with this idea a bit more in the past days > and ran into a problem: Converting the inline documentation into > Docbook, and transforming it into HTML later on, does not work out > very well: The intermediate step between inline documentation and HTML > is cumbersome, because one has to ensure that the generated XML files > are valid, and it takes a lot more time to convert from Docbook to > HTML than it takes to convert to HTML directly within phpDocumentor. > > Because of that I'd like to suggest to drop exporting to Docbook and > use one of phpDocumentor's HTML renderers instead. You mean we should generally avoid docbook in the future and use html directly you say? I always believed that docbook was the magic solution to have a clean and structured doc. Also do you plan to generate PDF-docs (manuals in PDF-format) out of the HTML-documents? There has been discussion recently on the list (though I didn't have time to follow it in all depth) about livedocs and a different intermediate format afaik. So if we're going to change from docbook to something new, maybe we could move to a different, more easy format? 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) ... Stefan