[crossfire] Documentation / handbook / playbook / spoilers

[Kevin R. Bulgrien]

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