[crossfire] Documentation revamp, was spoiler generation

[Nicolas Weeger]

>   Can you give some better examples of that?

Well, I'd say the documentation doxygen generated in the html directory could 
nicely be bundled.
As a test I added a page for "timers", accessible from the "related pages" 
tab, or from the "timer.c" file page.

>   I will admit that the current layout of documentation (or maybe more
> specifically, the doc dir) isn't great.  To find out if something is
> documented, one basically has to resort to grep, as what file something is
> documented in isn't really the most consistent.

Which is why it makes sense to put all (code-related) documentation in an 
organized way.

>   I'm not sure what the doc structure should look like, but it definitely
> needs to get cleaned up.  One complication is that there are potentially 3
> different audiences for any documentation: players, mapmakers, and coders
> (one could perhaps even add a fourth - script writers).

Yes. Which is why it's easier to be able to see all files, and organize all in 
a coherent way - main page, 3 sections, one for each profile :)

>   Now one method is to basically split that information into 3 different
> places - the player information may be in the help files or the client. 
> The map maker information may be in the editor, and the developer
> information may be in the code itself.  The problem is that makes it pretty
> hard to find the relevant documentation.

Organisation :)

>   Now if doxygen can be used to somehow separate these pieces out, that
> would make me more willing to look at it.  For example, something like
>
> **start_help_...
> help documentation
> **end_help
> **start_editor_...
> information for the editor
> **end_editor
> (rest of this is just coder information, so doesn't really need to be
> pulled out)

doxygen apparently does that nicely. Check 
http://www.stack.nl/~dimitri/doxygen/commands.html#cmdif

>   I'd still say that even in that case, doxygen should be used more as a
> documentation building tool and not a formatting tool.  In fact, for the
> vast majority of documentation, I really like plain text - I can always
> view it easily, update it easily, etc.  I'd think that for most of the
> documentation, there is actually little need for formatting in most cases.

Except for bundling purposes, of course. It's easier to have all in the same 
format.
Note that it may be possible to just instruct doxygen to include plain text 
files. No formatting, but it would be part of the formatted page anyway.
I guess http://www.stack.nl/~dimitri/doxygen/commands.html#cmdverbinclude 
would do the trick.

So we could have both - plain text files for quick reference, bundled / 
formatted documentation.


Nicolas
-- 
http://nicolas.weeger.free.fr [Petit site d'images, de textes, de code, bref 
de l'aléatoire !]
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://mailman.metalforge.org/pipermail/crossfire/attachments/20070716/59d3fab3/attachment.pgp