[crossfire] Documentation / handbook / playbook / spoilers

[Mark Wedel]

Nicolas Weeger wrote:
>>   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).

  I think you may have mis understood me.

  The problem with dependencies, which could be done with currently spoiler and 
playbook, is often time you will get false positives (the archetypes file looks 
newer, but in fact has no changes).

  Since generate docs takes a fair amount of time (have to collect images and 
other data), it is generally not desirable to do it all the time.  Which is why 
there is an implicit requirement that make doc is run.

  The other issue is that make documentation may require tools that most users 
don't have, and most servers probably don't care about doc.

  I'd almost argue that the docs should be pulled from the server area (except 
those specifically related to the server, like programming and protocol 
information) - if anything, it'd almost make more sense for them to be in the 
client.

  This was one reason periodic doc archives were built - expecting the bulk of 
players to download the server and archetypes and have all the tools just to get 
the docs was a bit excessive.

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

  another issue was that the images got converted to gif format - this was 
certainly needed back in the days of bmp or xpm, when few browsers could read 
them.  PNG is standard enough, that converting them to another format probably 
isn't needed.

  However, some form of collection is still needed - you don't really want your 
image paths to be ../../lib/arch/../../...png, so another thing the conversion 
process does is copy the images over.

  One reason is that the ideal case here is that I can copy everything in 
spoiler-html to some directory on my webserver, and point people at it and have 
it work.  So you can not do relative paths here, as that makes copying that data 
much more a pain.

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

  I guess it depends on what the goal is.

  If the goal is to remove the extraction scripts that extract data from source 
files, doxygen seems a fine replacement for that.

  However, I'm not sure that then means that the entire doc should be redone in 
doxygen - that seems way overkill, and actually seems counter productive - html 
is a lot more well known in doxygen, and I'd rather we stick with things that 
are more common for documentation that go to something relatively specialized 
(at least as far as knowledge is concerned).

  the spoiler already does server sides for the html files, so that seems like 
that would still work fine, and not require nearly as many changes.  I suppose 
some of this is basically the question of whether the basic format should be 
doxygen that includes other files, or html that includes doxygen generated data.