[crossfire] Documentation / handbook / playbook / spoilers

[Nicolas Weeger]

>   Can you effectively do a handbook/spoiler doc with doxygen?  It seems
> that doxygen is aimed really for extracting information from code to make
> guide data, less so for freestanding documents.

Obviously you can, since the doxygen site itself was (apparently) done through 
doxygen :)
http://www.stack.nl/~dimitri/doxygen/ states that, at least.

Also, if you look in trunk's doxygen generated doc, you'll see a page on 
timers (from the 'related pages').

Granted, the generated pages will have the same look as the code-related docs. 
But shouldn't be too hard if we want to extract this information (or even 
create a second doxygen.doc file) just for the playbook. Could even be 
processed twice, once as part of server doc, once part of player doc :)


>   In theory, make doc is supposed to do that now.  By default, it doesn't
> do the spoiler and playbook I think, because there is no good way for make
> doc to know if they changed (since a lot of data is based on archetypes, it
> is really if the archetypes change).

Assuming we include the doc, doxygen will handle that for us.
The idea would probably be to generate a doxygen-suitable file from archetypes 
and such.
(I'd suggest to have files named .dox for playerbook and such).

>   One issue/complication you would run into, which currently exists for
> playbook and spoiler, is multipart images.   There are scripts in the
> spoiler which know how to reassemble the small multipart pictures into the
> single large picture.
>
>   The ideal fix for this is to make it so that there are no multipart
> images out there - everything is in big image format, since that is now
> supported.  If that is done, then the extra code/complication of having to
> do multipart image handling is removed.

*nod*
We can fix that as needed.

>   And maybe:
>   To make changes, use would need to know doxygen formatting commands,
> which if you're a coder, is probably fine.  But if you just want to write
> documents, html editors are pretty common (or lots more people probably
> know how to write in html)

AFAIK you can include HTML code directly in doxygen. So for player-related doc 
we could put that in a doxygen-enabled HTML format (probably adding a /** 
@file xxx header could be enough).
And people could just submit as plain text, that'd work too.


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/20070708/c5f1f2dd/attachment.pgp