XML Reference

[hailstone]

I think there is a need for a faction that is separate from Magic and Tech that can serve as a reference and testbed for GAE features. I thought about calling it Shibboleth (see http://en.wikipedia.org/wiki/Shibboleth and http://www.ruf.rice.edu/~kemmer/Words/shibboleth.html). I haven't done anything yet, just putting the idea out there.

Edit: Changed the title to better reflect the topic. It's more generic than just a reference faction now.

[John.d.h]

I'm planning something like that in a few months, but it's bigger and farther-reaching than what you're talking about.

http://ow.ly/3sjKU

[hailstone]

What I'm suggesting isn't intended to be a "playable" (as in balanced and aesthetically pleasing) faction, more of a demo of features that modders can use as a reference and programmers can use to store the xml (and other data) for new features. Currently new feature data is either temporarily added to magitech or made an attachment to a ticket.

[Omega]

Sounds like a bit of work, but from a modder point of view, that would be great! I've lost track of how many features slipped under the radar because the modders never realized they were implimented or because they had no clue how to do them... Of course, on the same topic, won't one of you GAE pro's help the Wiki? The GAE section is growing out dated, especially with the listing of new features and how to do them, as well, the emanations and effects code was outdated (caused some problems in military when trying to add some effects using that old information).

[silnarm]

This is probably a good idea, I'm partial to just attaching addons to the tickets, but a complete tech that used most, if not all, available features would probably be a very handy reference.

@Omega: I think the incorrect flag names were corrected, I'll try to get the Effect/Emanations stuff cleaned up soon, but if you can provide specific complaints, I could perhaps attend to those areas first...

[hailstone]

I've created a ticket for updating Wikia. I'm going away for a week but hopefully I can get started on a simple tech tree/faction.

[wciow]

I agree that the newer GAE features need some proper documentation, right now things are a little bit confusing and fragmented.

The final version of undead will be released sometime before the new year (hopefully), after that I plan on making a GAE only version which is closer to how I imagined the faction to work. I shall be asking questions and documenting as I go.

[Psychedelic_hands]

Constellus is planing on using most, if not all GAE features.  
Including lots of future ones.  So I'm sure we can help out you guys testing.

(There is no shameless self-promotion at all in in this post, I swear   )

[hailstone]

I've uploaded an initial version of Shibboleth Tech (it should work if you put it in the addons dir). It's a stripped down version of Tech faction from Magitech. To make it smaller I've referenced some of the larger files from Magitech. The only new feature included so far is teleport (I didn't keep my carrier example so I'll need to figure it out again).

I was thinking it might be better to keep the xml documentation with the source so it can be updated easily as new features get added. It would be autogenerated by Doxygen and uploaded to sourceforge at every major version. For an example of what it could look like go to CEGUI docs.

[silnarm]

Cool... I could start adding some stuff to it, but perhaps an addon uploaded to sf is not the best method for multiple people to work on it Shall we put in the repository?

[hailstone]

That was the idea. I just wanted some feedback before I pushed a lot of binary files that could end up being deleted (does git search for duplicate files?).

[silnarm]

'probably' would be my guess... in any case our entire repo is a ~75MiB download, about half of one branch checked out by subversion, so it's definitely doing something right.

The majority of the binary files will probably just be relative paths into magitech anyway, so I don't think this will be a big deal.

I say go ahead and push it all on.

Assuming you can... I'm hoping you are still on dry land ... ?

[hailstone]

The tech tree has been pushed. I'm still on dry land, only the surrounding roads out of the town were blocked but there was threat of the internet needing to be switched off yesterday in the city. I've also uploaded an example of the xml reference in doxygen format. I'm not sure if we should stick with the wikia or continue with this. Any thoughts?

[Yggdrasil]

Is it easier to maintain the doxygen files? Do you somehow extract these sites from comments in the source files? If you created these sites manually i'm more for using the trac wiki or wikia, keeps things together.

If we use doxygen we should upload it on the sourceforge webspace and link from the trac wiki.

[Omega]

I'd recommend the wiki by far. One source for all information (want to learn the controls? How to mod? What Military is?) that is very easy to update by anyone (GAE team busy? An experienced editor can do it for you!) is a huge plus.

Even with easier to maintain automatically generated files, you can just copy and paste the code. You can always have the doxygen stuff uploaded, since it can cover the entire source code (unfortunately, Glest isn't really well commented, nor optimized for doxygen ), but I'd definitely like to see it on the wiki too, at the least.

[hailstone]

It uses doxygen tags in a source comment to automatically generate the pages. It's no more difficult than wiki syntax. (see http://www.stack.nl/~dimitri/doxygen/commands.html#cmdpage for an example). Doxygen is very capable of being used for GAE. Silnarm (and I think Daniel) has added quite a lot of doxygen comments plus I add them to my own work when it's appropriate. I've been uploading doxygen documentation and linking from trac for a while now (at the release of 0.2.13a and 0.3).

There are benefits to using doxygen for the xml reference: it's an official source (ie not everyone can modify it, though patches can be sent to developers), closer to the code so it's more likely to be updated, all the benefits of having it in git, easily released with the game, no wikia ads, link to relevant code and examples.

I'd recommend the wiki by far. One source for all information (want to learn the controls? How to mod? What Military is?) that is very easy to update by anyone (GAE team busy? An experienced editor can do it for you!) is a huge plus.

From what you've said previously there's information that no one but the GAE team can provide so for reference information it's not so useful that everyone can modify it. I see the info as three parts: user info, modder tutorials and developer/reference info. The information can still be all together for the particular audience.

Now I've made a case for using doxygen I'm going to agree that it shouldn't be used  (at least not for now). This is so the xml reference for GAE and MegaGlest can be stored in the same place. Engine developers can then see how to implement a missing feature to maintain consistency (or compatability?). Currently MG is using separate pages for their XML reference. I propose to have pages for Glest 3.2.2 and then a set of pages that combine the xml (and lua?) reference for GAE and MG that have the common parts as well as the specific parts for each.

As a side note I think translations are a similar situation. There's no point duplicating efforts for slightly different wording with the keys.

[John.d.h]

As a side note I think translations are a similar situation. There's no point duplicating efforts for slightly different wording with the keys.

I would think the best way to handle that would be to combine the lang files (GAE with MG) before shipping them off to the translator, and then splitting them again once they've been translated, so they only have to be done once and then updated periodically.

[silnarm]

It uses doxygen tags in a source comment to automatically generate the pages. It's no more difficult than wiki syntax. (see http://www.stack.nl/~dimitri/doxygen/commands.html#cmdpage for an example).

My only concern with this is that it will not be as easy to maintain as you perhaps think.  The 'ProtoType' classes, all the stuff that modders define with XML, forms a very nice 'class zoo' in the source, so many of the parameters available will not be immediately obvious in the source, because parts come from from one or more super-classes.

Of course, this problem is common to any method of documentation, and 'in source' doco would probably be preferable.

However, I was quite fond of the format I am now using on the wiki (ie Command XML) and I'm not sure how well that could be reproduced with doxygen, but I'll have a play around with it.

[ultifd]

So how come I can't seem to repair transformed defense towers? Also "Become farm" should be "Transform to".
Nice work, I'll test it more after the crash is fixed  Maybe I'll try the code myself? Hehe...

[silnarm]

So how come I can't seem to repair transformed defense towers? Also "Become farm" should be "Transform to".

The defence tower wasn't in shibboleth initially, I added it so I could test some stuff with housed units, and obviously didn't add it to the worker's list of repairable units.

Just thinking about it now makes me wonder though, should a transformed building be repairable before it finishes its own construction? Might make that a flag...

[ultifd]

So how come I can't seem to repair transformed defense towers? Also "Become farm" should be "Transform to".

The defence tower wasn't in shibboleth initially, I added it so I could test some stuff with housed units, and obviously didn't add it to the worker's list of repairable units.

Oh, sorry, I didn't know that.

Just thinking about it now makes me wonder though, should a transformed building be repairable before it finishes its own construction? Might make that a flag...

I suppose in some cases they could, for other mods, but usually they shouldn't...probably.