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. _______________________________________________ crossfire mailing list [email protected] http://mailman.metalforge.org/mailman/listinfo/crossfire
