[crossfire] Documentation / handbook / playbook / spoilers

[Nicolas Weeger]

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

So? Put the doc in doxygen format, and require a make archive (from server 
root) to generate it :)

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

This is especially true for Windows users. Doc requires awk, Perl, egrep, 
tools you'd need to install (and find first).

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


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

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

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

>   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)?
Just look at the various files, feeling like updating all header numbers by 
hand because you added a section? :)

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


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/20070709/7c8dbf14/attachment.pgp