xml editing (POS2) documentation

ff03k64

I was thinking that the POS2 xml isn't the easiest place to figure out everything that the engine can do. The biggest problem for me is just finding the right part of the document. I was thinking of trying to make it easier to navigate in some way and thought it would be useful to post it here as well, both for help making and for others to use.
It also seems like there are a few things missing too.

A google site crossed my mind, or just a google doc. Something that i can put links and a table of contents into. It would also be nice if it can keep the xml formatting and color coding if possible. Any suggestions? Is there already something made?

LaFayette

This is a good thread to raise. There is a wiki out there with the TripleA XML options that lists things very nicely, but I can't find the link. So that is a good resource.

1) One stop shop documentation - index of links & resources in one place -> where?

I think we should have a one-stop shop somewhere where we can get all of the map maker documentation resources. This could be a simple as an index of links. I've thought for a long time that the pinned forum posts to document items does not work well (reasoning: not indexed, gets cluttered, scattered, is not updated even when we have good intentions, updates are not readily noticed, hard to do cross-post updates and ensure it's complete across all posts and threads).

First question, should we have such a one-stop shop, and where? Our options are:

Website, something similar to "https://triplea-game.org/user-guide/" but for map-makers
triplea-game/docs https://github.com/triplea-game/triplea/tree/master/docs/map-making
Forums
Pos2.xml

2) Converting XML attribute values into tags so that they appear in DTD

The XML DTD is pretty useful for knowing which tags and attributes are avaialble, but that really just touches the surface of it as many of the really interesting options are attribute values. I'm thinking we may want to expand on this quite a lot and restructure the XML to make this implicitly documented and something that the DTD would capture. For example, instead of:

<propertyList>
   <property name="ww2v3" value="true" />
</propertyList>

We would have:

<propertyList>
     <ww2v3 />
</propertyList>

With the above, the 'ww2v3' would actually appear in the DTD file and could be validated.

3) RE: POS2.xml

While having a sample XML is good for explaining, it causes problems for development as well. If it were minimized, it would help. It's lengthy, and for example I recently tried to clean it up to remove the unnecessary <boolean /> values and it was daunting to update seemingly a hundred lines of XML.

I think we might do well to create a minimal sample XML and have that be its own resource but not the resource for all of the available options.

My best thought for resolving this is to create a single documentation page per XML attribute. That page would get a standard look to it and be essentially a series of tables that describe all of the possible values and what they do.

Having that on website would be nice for an easy place to find it. Having it be in triplea-game/docs would be convenient for developers as we could update it at the same time as we update the code and it'll have a better chance of staying up to date. It'll also probably be easier for people to modify it I believe, secondly it'll keep documentation more together as we'll have all the other documentation colacted with it.

A google site crossed my mind, or just a google doc. Something that i can put links and a table of contents into. It would also be nice if it can keep the xml formatting and color coding if possible. Any suggestions? Is there already something made?

@ff03k64 one thing we need to really consider is maintainability. This is a core problem I think with POS2 and so we may run into the same trouble with another document and then have yet another document that is started and not complete and perhaps out of date (which seems to be the story of TripleA documentation).

I think the first step here is to agree on (1), where we really want all map maker documentation to be. Then we can create any new XML documentation there, consolidate everything else to that location and organize and simplify it all.

LaFayette

Here's the link I was looking for: http://www.starlords3k.com/XOB.html, the XML browser was a sub-thread in the forums here.

LaFayette

http://www.starlords3k.com/XOB.html is a great resource, but I think it demonstrates our duplication and discoverability problem. It has not been updated with new items and some deprecated items are still listed. For example, the loader tag should not be needed at all anymore amongst others. I think TripleA probably would do well to import the XOB.html onto our website in some manner, or triple-game/docs and then it could be kept up-to-date.

ff03k64

@LaFayette I just looked at the XOB again, and it is way better than I was thinking it was. I can't speak to it missing things or having deprecated things, but I had never noticed the hierarchical sort option before, and that should be the default IMO. Much more useful I think.

I had two reasons that I thought a Google doc or site would be good, so anything that does them I would also vote for.
First is that I could do links. My original thought was to just put the POS2 xml up, and put links to the different sections, like triggers, conditions, etc.
Second reason was that I know it is easy to let different people edit, or let everyone comment.

I do think that for the XML, it would be useful for it to keep formatting (and maybe color coding that notepad++ gives).

I looked briefly at the game docs, it didn't seem very intuitive to use to me, but I might not have given it enough time.

What is DTD?

LaFayette

I do believe we need to decide where the general "home" for map maker documentation should be.

@ff03k64 , DTD = doc type definition. It defines the set of valid XML tags and attributes, and their relationships. TripleA heavily uses magic attribute values that arguably ought t be tags in their own right. Regardless, the DTD is a validating document and can tell you if your XML is valid. As a form of documentation itself, it can tell you the total set of allowed XML tags and attributes

https://github.com/triplea-game/triplea/blob/master/game-core/src/main/resources/games/strategy/engine/xml/game.dtd

Panther

@LaFayette

I do believe we need to decide where the general "home" for map maker documentation should be.

I second this. Currently the wiki-entry:
https://github.com/triplea-game/triplea/wiki/How-to-create-custom-maps
refers to
https://github.com/triplea-game/triplea/tree/master/docs/map-making

which is quite counter-intuitive, as clicking on any link there in Github of course shows the source code.

So unless I missed something in order to properly see the html-files I need to download the TripleA source-code to extract the files from the zip and open them locally with my browser.

The content of those files as well as the XML-guide or even the POS2.xml file should be accessible maybe through the website or Github.

LaFayette

@Panther It looks like the HTML files need to be converted to 'md' files to properly render. You can otherwise click on the MD files and they render through a web browser, eg: https://github.com/triplea-game/triplea/blob/master/docs/map-making/map-features-change-log.md

Panther

@LaFayette Indeed the md-files do render properly. But I was especially addressing the html files, as those offer other valuable content (I have been asked about a documentation that those html-file would offer, but wasn't able to return a proper link but only the above stated workaround instead).

LaFayette

@Panther the two HTML files are now updated to be MD, they'll render now.