Entity template documentation

[Ykkrosh]

The game's various unit types are defined in XML files like this. It seems useful to have documentation for the file format, so that people can understand what it all means.

With the old simulation system we have documentation on the wiki that describes the syntax and the higher-level design, which is good. But one danger is it becomes incomplete and inaccurate, e.g. the armour syntax there doesn't match what's actually used in the old entity template files. So what I'm trying to do with the new simulation system is have the syntax definition embedded in the source code, so that it's easy to keep in sync with the code and so it can be used for automatic error-checking of the entity XML files too.

The XML validation part is already implemented and running, and now I'm trying to generate human-readable syntax documentation. I have a conversion tool that half works now (using XSLT on the RNG schema to generate HTML), and I'd like to check with people if the output is generally sensible and whether there are changes that would make it more understandable, more informative, prettier, etc. The current output is here - lots of components are missing text, but Armour and Attack and Health and Position are mostly complete. I don't want to do anything extremely complex here but I'd be happy to make some changes to help people who'll have to read this and use it to edit the entity XML files. Any thoughts?

[feneur]

Would it be possible to have two versions of this? I.e. one for programmers who needs the "deep-down" version, with the RELAX NG Grammar and so on, and a simpler one for scripters/modders/artists who might want to/need to edit these files? That could be too much work/make things unnecessarily complicated, but at least a notice at the top which makes it clear what goes in the actual XML file and what's for the game to understand so to speak. I'm guessing (/hoping) there will be examples in each section as well which would help a lot (and lessen the need to split things/oversimplify).

I'm not sure if it's just me, but it can be hard to remember exactly what's the difference between integer/decimal etc, do you think it would be possible to add some quick reference, either to each listing of Value type (which sounds a bit too much) or a cheat sheet at the top of the page? I'm not sure how much use it will be, but it would make it easier to edit/mod the entities. And since editing the entities is something that's probably going to be needed to be done a lot when we start playtesting + it can be a boring/menial task it would be nice if it would be as easy as possible to allow for as many as possible to do it.

[Ykkrosh]

I could just get rid of the Grammar section entirely, because the other descriptions ought to be sufficient for anyone who wants to edit the files. (People who want the explicit grammar for other purposes can get it from the source code). Mostly it's there so that I can see bugs in the conversion script, which is hopefully only a temporary need

For the data types, maybe a couple of examples each time would be helpful, and would be easier for readers than checking back to the top of the page each time they forget? so it could say "integer (e.g. -5, 5)", "positive integer (e.g. 1, 5)", "non-negative decimal (e.g. 0.0, 0.5)", etc.

[feneur]

Sounds good. And don't worry, keep the grammar section as long as you need

[Ykkrosh]

Uploaded an updated version with examples for the datatypes, and with the grammar disabled by default (toggled by a checkbox, unless you're using a stupid buggy browser like Safari or Chrome which don't handle dynamic updates with the '#show-grammar:checked ~ * div.grammar-box' CSS selector).