Sounded to me like offline support was in-lieu of online support. The most brute-force option here is to just host on website as an html.

Overall it seems we are weighing three options:

• maintain the data as an html file (post-render) hosted directly on website repo.
• create dynamic html page that is hosted on website repo, feed the page a JSON payload that is rendered from a YML file
• create dynamic html page that is hosted on website repo, feed the page a JSON payload that is rendered from a set of input files (eg: all files in a given folder)

Let me know @RoiEX if I mischaracterized the recommendation.

Thanks for feedback.

To build on how yaml knows about the double colon, it knows based on the first letter after the first colon. There are three choices, 'string', 'list', or 'map', if it sees a [, it's a list, { for a map, and any letter is a string value. You can also do lists in a different syntax, multi-line as:

list_name:
 - a
 - b
 - c
same_list_values: [ 'a' , 'b', c' ]

And for a map:

map_name:
  - property_a: 1
  - property_b: 2 
map_name { 'a': 1, 'b': 2 }

And you can nest these, so hence why we have a superset of JSON.

YAML provides block values with native HTML without any escaping, so it's just a nicer format to work with and avoids the error prone syntax requirements of JSON.

The idea is that we basically structure a YAML to match the needed JSON, work with the YAML by hand, and use software to do the relatively simple conversion to JSON and upload to website (we have an existing pattern for doing that).

All that aside, simply hosting the HTML directly on the triplea website is a good first option! : )

That would be just plopping the file in: https://github.com/triplea-game/triplea-game.github.io; Then it'll be available from http://triplea-game.org/theFileName.html

@redrum

@LaFayette I don't want to put the comments in the engine source code as then no one but developers would ever maintain it. Its better in a place that map makers can also contribute to.

I don't think that is the right concern, but I would want it to be so that developers would keep the source data up to date when adding new attachments, but open for anyone to modify and improve the documentation at the same time.

We essentially have this model with triplea_maps.yml. While not perfect, it has worked out that more than just developers can update the file.

I checked out the source code further, it's not in good shape to accept more information as either additional javadocs or java annotations, so keeping this info in java source files I would agree is not a good one.

@mahks said in XML option browser:

The HTML page is pretty straight forward. Could be maintained by anyone with HTML. I could do it for now.
But I think the most important thing is getting the data in a portable format.

I generally agree, but I do think there are a some additional important questions to decide/answer:

• how to integrate this as an official tool so we can keep it up to date now and for the long term?
• will the web server hosting technology integrate with the rest of the TripleA infrastructure, will it add another server to be managed and maintained?
• will there be overhead or delays in deploying any data updates to the web server?

I like the tool as presented and I think it would make sense for it to be part of the official project. I think two really good options to do that would be either:

1. Similar to the maps yaml file, host a yml file that is updated when we update source, on updates the yml data would be transformed to JSON and uploaded to website (we do this about exactly for the maps.yml data today).
2. Host the HTML file independently from the source code but on the github website directly. Github.io uses a jekyll, it can render HTML natively.

The first option has greater one-time setup cost, but data is pure from presentation layer and can be updated at same time as source, so lowest maintenance cost over the long term compared to the second option (which is also completely viable too).

Any third option (is very welcome), but would have some challenges to solve for the concern of server maintenance overhead in addition to keeping the data well maintained over time.

Very nice work.

We could do a special commentary syntax in the source code where attachments are defined. On each build we could fire up a script that then scrapes these comments and produces a JSON that is then delivered to a 'data' section of the website and would then be available as a javascript variable. This is pretty similar to how the maps page is populated: http://triplea-game.org/maps-list/maps/

@Mahks if you can handle the front-end part, with jekyll, and assume you have such a JSON variable, I could do the backend scraping and deliver the JSON. https://github.com/triplea-game/triplea-game.github.io

Thoughts?

As a suggestion, does it clean things up at all to hide the zero's? (ie: 0 (+0))