On Tuesday 10 July 2007 23:20, Kevin R. Bulgrien wrote: > > > My opinion is doxygen including html, since doxygen will handle other > > > conversions for us (chm, pdf, ...) > > > > See note above. We really should stick with only 1 other formatting > > language > > beyond plain text to keep things simple and easy to update. I vote HTML > > since > > it is incredibly standardized, plus there are a large number of WYSIWIG > > html > > editors. Are there any WYSIWIG doxygen tools out there? > > For whatever it is worth, HTML is ubiquitous, and so would get my vote. > > As Mark, I can almost do HTML in my sleep and have no clue about doxygen. > Also, > FWIW, the htmldoc tool is an excellent tool for generating pdfs from html > even so > far as to create a collapsible tree section index.
I know this is an old thread, but I spent a lot of time today reviewing doxygen and trying to wrap my mind around it. I am changing position on this - at least for code documentation, Doxygen is not hard to work with. The conventions it has are good procedure anyway, and code documentation is poor in a lot of areas. As I have done a lot of work on the gtk2 client, I tried out using doxygen on it, and was impressed. It gives me a phenomenal overview of the code base, and I don't even have to use a GUI. Navigation with the likes of lynx/links is excellent. The coding style guide can easily show how it works without adding a lot of text to wade through. See some of the recent changes in http://wiki.metalforge.net/doku.php/coding_style_guide to see what I'm talking about. Comments welcome on those changes. If there is not a volume of dissent, I'll filter them back down into the document in SVN. On generating documentation that is not based on code, I cannot say for sure as I am torn about having to learn yet another formatting tool, but since it looks like man pages can be output too, so I'd probably take a another look for the reason given above with respect to using a unified format. FWIW, though, looking at the .dox files in server/doc/Developer, they look reasonable, and easier to maintain than HTML, and beyond easier than maintaining a man page source file, but, I do recommend developing a condensed style guide on the wiki that takes the sting out of making people learn one more formatting tool. Documentation is already hard, and a new tool doesn't need to be the excuse to keep not doing it well. Kevin _______________________________________________ crossfire mailing list crossfire@metalforge.org http://mailman.metalforge.org/mailman/listinfo/crossfire
