"Niels Reedijk" <niels.reedijk@xxxxxxxxx> wrote: > There are pros and cons. Many of the people here have 'grown up' with > the Be Book and that's probably why there is a hang towards the > original structuring. However, many of the audience we might reach > have not. And don't forget that we have a lot of power over the > output > - either by CSS and HTML headers, or crudely by hacking into doxygen. It's not a matter of being grown up with the BeBook - because I didn't; I just dislike the doxygen style documentation a lot. I consider doxygen to be an inferior tool for its job. If you want to see how Doxygen should work, have a look at Javadoc; even the default output is much better than anything you can produce with doxygen. I don't think Javadoc is perfect, either, but at least the output is what I would expect from such a tool. > The current doxygen XML output is considered to be bad, but I saw on > their mailing list that a newer XML structure is in the works. If I > would develop doxygen, I would consider moving over everything to > XML, > and indeed use XSLT to transform the data to other formats. It would > make doxygen a bit less hackish (to me). Definitely, the current output (be it HTML or XML) is just bad and not really made for use with either CSS or XSLT. > Just to be clear on the XML position. I sort of agree with Ingo that > humans are not made to read and write XML. I have been cheating > somewhat, as I'm using an XML editor, so I don't make any mistakes > with regard to the syntax and the structure (which Docbook imposes). > I > also don't want to denounce using Docbook altogether. The UI > guidelines are the perfect example of something that should have been > (and is) written in docbook. It's just that this documentation > doesn't > require to stay in sync with headers and has links all over the > place. FWIW I agree as well, I just had the impression you actually wanted to code some tools that would automate the task. > The user documentation team will need to have a good discussion on > this issue. I have some thoughts, but it belongs in another thread. I wouldn't even mind if the user documentation would be written in a Wiki, and exported to PDF and HTML from there. Even though Docbook sounds like a good idea there as well. > So how to proceed? Since I would still like to have the possibility to generate Docbook, I think we should aim to be able to produce good XML output out of our documentation sources. Since doxygen is, in many regards, an inferior tool to create documentation, I wouldn't like to use it, though. However, there are many alternatives to doxygen, and its syntax seems to be very similar to other options, if not compatible already. Therefore, as long as we don't actually use doxygen to produce our final docs, I'd be okay with using its syntax for now. IMO we should just check the existing alternatives one by one, and see if one does the job in a better way, and eventually is less file centered and allows for more and better grouping. If we don't find a viable alternative, there is still the option of extending an existing tool to do what we want. After all, we still have plenty of time until R1. Bye, Axel.