[crossfire] Documentation / handbook / playbook / spoilers

[Mark Wedel]

Nicolas Weeger wrote:
>>   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.
> 
> Except then you couldn't easily link to actual server archetypes / 
> artifacts / ...
> I'd argue archetypes / artifacts / ... are server-dependant. Generated doc 
> really has 2 things: Crossfire "core" things, and "server-related" things - 
> archetypes being in this last category, since it's easy to change/add things.
> 
> It could make sense to put player-related doc into the client, of course. But 
> maybe we want to reduce the dependancy for client to the maximum?
> (or it could be in its own specific project to not depend on any client)

  Maybe.  But as things are right now, some docs are perhaps rightly placed in 
the server (those documenting functions, or more server internals).  But having 
the player docs be in the server makes little sense to make them available to 
players.

  Now some of that player documentation has a build process involved (like the 
spoiler or handbook), so having it be separate causes it's own set of problems. 
  OTOH, still using makefiles for the documentation, and having to do a 
configure with parameters pointing to the server and archetypes to use may not 
be terrible (and if those are not set/configured, it doesn't build those pieces).

  OR maybe already have those pieces extracted, and update them as needed.  For 
the handbook, this probably isn't that big a deal (it isn't extracting too much 
data, and even that it is could probably be simplified - don't necessarily need 
to show an icon of every building in the game, etc).  But for the spoiler, while 
a lot of the data doesn't change much, there is actually little static content 
to that - most all of it is data that is pulled out.

> 
> 
>>   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.
> 
> *nods*
> Except right now it does require the archetypes anyway, and the server. So 
> we're stuck :)
> (the doc relies heavily on eg crossfire -m4 to get information to process)

  Some of the docs do, some don't.  But the distributed doc archives included 
all the built data, so an end user would just untar it and didn't need to do 
anything more.

> 
>>   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.
> 
> Yes, but that isn't an issue - doxygen would copy too if needed.

  but you still need to figure out what those files are that need to be copied - 
I suppose doxygen could do that, but we have current tools in place that do that.

> 
>>   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.
> 
> The goal is to have a nice documentation for players, in various formats :)

  If that is the goal, this is then a broader discussion - it is basically 
asking what should the standard document format be, as even for the static data, 
there are at least a few different formats floating about (smooth.tex, 
extmessage-types.html, and then most are just plain text).

  I'd almost suggest that perhaps the documentation in general should be redone. 
  What is a sensible directory layout (SVN gives us good renaming ability, so 
moving stuff about shouldn't be a problem).  What should the standard format(s) 
be?  text + html?  text + doxygen?  text + something else?

  In general, text seems to work fine, but there are times when something that 
gives a bit more formatting ability is needed, even for developer information. 
So we should figure that out.

>>   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).
> 
> *shrug*
> How often do people contribute documentation? How many who are not developers 
> (and thus can be assumed to know enough doxygen)?

  I don't think that is a good rationalization - I contribute documentation 
(just did yesterday in fact).  And I certainly know how to do fairly advanced 
formatting in html.  I don't know how do that with doxygen.

  As you mention, you can embed html in doxygen, but if that is done all the 
time, then really, is there much point to using doxygen then?  And at that 
point, we really have 3 formats used for documentation - text, doxygen, html - 
if you're not proficient in one of them, you may find that you are unable to 
easily update some documentation.

> Just look at the various files, feeling like updating all header numbers by 
> hand because you added a section? :)

  Probably not.  But if it is in html, at least I'd know how to do so.  With 
doxygen, have no idea.

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