[crossfire] Documentation / handbook / playbook / spoilers

[Mark Wedel]

Nicolas Weeger wrote:
> Hello.
> 
> Kind of resurrecting this thread, but well :)
> 
> 
> I was wondering what people would think of "centralizing" the documentation in 
> the doxygen format.
> Not necessarily to make links to the code, but merely to have one big 
> (server-side) reference documentation.

  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.

> 
> The pros I see for this are:
> * only one format to handle, doxygen converting to html / latex / chm /...
> * only one generation process - run eg make doc in root, will generate all the 
> documentation including handbook / plabook / spoilers

  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).

> * easy to point to technical documentation if needed (example: "armours are 
> thus and thus - see this file for technical details)
> * easy to create dot schemas if wanted
> * can integrate archetype pics (possibly from arch, which is hopefully linked 
> from /lib anyway for make collect) without too much duplication

  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.

> 
> and the cons:
> * requires doxygen
> * no text-only output - doxygen apparently doesn't do that
> * probably other things I'm missing :)

  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)