Replies: 5 comments 12 replies
-
|
I'm favorable to the suggestion. What is involved when you say "add"?
I wonder whether same repo or new repo make would make more sense.
…On Sun, May 12, 2024, 3:05 PM asvitkine ***@***.***> wrote:
I propose we add the XML option browser to the repository.
For reference, this is what I'm talking about:
https://forums.triplea-game.org/topic/729/xml-option-browser?page=1
http://www.starlords3k.com/XOB.html
The main advantage would be that we could keep it up to date with changes.
It's already a bit out of date, since it hasn't been updated with recent
changes.
I had tried to contact the author for a few times to see if he could
officially bless this, with never any reply, but then I just re-read his
forum posts and saw this post:
I wanted the tool to be usable off-line, so that is the reason for the
format. If you wanted to use the data or the tool in the website, that is
fine with me.
https://forums.triplea-game.org/topic/729/xml-option-browser/8?_=1715551370156
To me, that seems good enough as permission to upstream it.
—
Reply to this email directly, view it on GitHub
<#12580>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/AC6SZOPQL3DPXB7RHTX4OCDZB7RUDAVCNFSM6AAAAABHTEK2O6VHI2DSMVQWIX3LMV43ERDJONRXK43TNFXW4OZWGY2TOMBZGI>
.
You are receiving this because you are subscribed to this thread.Message
ID: ***@***.***>
|
Beta Was this translation helpful? Give feedback.
-
|
Will PoS2 remain the main official reference on game-making? Is this going to double documentation efforts, in that every time one would need to update both this and PoS2, with the risk of inconsistencies between the two documents? Will it be easier or harder than PoS2 to update for the average user with no specific skills and how much? It is needed to be very clear about which one is the main document if we are going to have more than one covering the same matters. Having both and just letting the single user take care and update whatever of the two they prefer is likely going to cause issues and confusion. |
Beta Was this translation helpful? Give feedback.
-
And asvitkine wrote:
My 2 cents, single source of truth is important. PoS2 might be showing some age & lack of flexibility. I'm not entirely sure it's possible to actually have and demonstrate all options in a single game. What's more, an XML browser type thing can have examples and be a lot cleaner than relying on a large blocks of XML comments. What's more PoS2 has gotten a bit dated (which means there is yet more effort if we want to revive that as the authoritative reference). The PoS2 map is still a useful reference nonetheless. Perhaps we can make this decision once we see what it looks like when we are hosting the XOB ourselves. We do need to ask ourselves which is a preferable reference, a sample XML file or the XOB. If the XOB is not easily the preferred reference, it would be a wrong move. Though, it was made for a reason, and I recall being quite impressed with it. I suspect it'll be a much better reference doc & easier to be updated. The PoS2 map has not been widely updated, mainly just by maintainers (and that is bad, anything that relies on just maintainers who have such limited availability is going to be a bottleneck and/or neglected eventually) |
Beta Was this translation helpful? Give feedback.
-
|
@DanVanAtta I was thinking of just committing it into the main repo, maybe in a sub-directory. I guess we could decide to just commit the json file that it uses and the actual web page could be omitted or to exist elsewhere. @Cernelius I think it would be best to stop using PoS2 and to just use the JSON file (and the web page around it). |
Beta Was this translation helpful? Give feedback.
-
|
Two issues: Bottom line, I'd put this functionality onto the main triplea-game website, or create a new repo for it. |
Beta Was this translation helpful? Give feedback.
-
|
@asvitkine side-note, just wanted to point out the 'discussion' format allows for 'conversation threads', akin to slack or MS Teams. You can reply to comments directly rather than creating a brand new comment. This difference in github discussion vs issue only clicked for me a few months ago. It's an interesting difference, and makes it a lot easier to have conversations with many deeply branching topics. |
Beta Was this translation helpful? Give feedback.
-
|
Also, I get that "XOB" means "XML option browser", but I suppose it should then rather be "XMLOB". However, I have some critics for this name (beside the fact of avoiding to make the acronym of an acronym). First of all, I don't think that the title should refer to the extension of something. The file is an XML file, but that is not descriptive of the file. It makes it sound like this is something about XML files in general. Moreover, how about if TripleA in the future would use the XML format for some other file somewhere else? Secondarily, "option" in TripleA has some specific meanings, so this makes it sound this documentation is only about the options (like the sub-categories of the various attachments which are called options). Thirdly, I'm not an expert, but what does exactly "browser" mean in this context? I think that "browser" is rarely used outside of the meaning of "web browser", so that sounds strange at least to me (but maybe not to someone with an actual technical knowledge). Is calling this thing a "browser" correct? I just don't know. Let me know. So how about changing the name from "XML option browser" to something like "TripleA Game File Language Information" or "TripleA Game-Making Guide"? I don't know if these ones are really good names, but I'm just making examples if the developers can find some better name for this thing. Am I right? |
Beta Was this translation helpful? Give feedback.
-
I don't think that we need to be that worried of duplication. I'd just update it clearly as to state that it is not any longer the main reference with the date when this decision has been taken and leave it alone as you would do with whatever game made by someone who decided to write stuff within it. Then, if anyone will want to update it anyway, that would be a plus because I do think that the concept of showing the features within a game is valuable and there is no need to do so for ALL OF THEM. Really, it would only need to be updated when a relevant feature is changed, not necessarily when a new relevant feature is added (and it seems that neither is going to happen very often, unfortunately). I surely advice against removing the comments from PoS2. What will need rewriting is rather anything in the documentation which states that PoS2 is the official game-making guide if you'll have XOB taking over. PoS2 is already hidden well enough that it is very unlikely that any new game-maker will find it on his/her own. Is it possible to run a mass search of the TripleA repository to see all instances where "Pact of Steel" or "PoS" or such are mentioned? I guess there are very few if any. Then, we'll have to check the pinned topics in the forum. I actually don't even remember if and where there is anything telling anyone to go read PoS2 in the map-making documentation. Myself, I'm not sure about moving from PoS2 to XOB. The most important thing, in my opinion, is that whatever is new is not too much harder than PoS2 to update by unskilled persons: anything which is the main game-making guide of TripleA needs to be as easy to update as a Wiki or at least not too harder than that (which is currently the case for PoS2). I'm neither in favour nor against what at this discussion (as long as PoS2 remains available as it is). As for PoS2, it is just important to make clear to anyone reading it that what is written may be out of date and it's basically just someone's game made at some point and updated for some version of TripleA. |
Beta Was this translation helpful? Give feedback.
-
This is the repo for 'triplea-game.org': https://github.com/triplea-game/triplea-game.github.io There is a markdown to HTML engine that converts most of the content, but content can still be vanilla HTML and HTML can be interspersed in the markdown as well. My impression is the XOB is just a JSON data file with an HTML page that is mostly JS to load & traverse the JSON data. My understanding to do that therefore is we need web-server hosting, HTML & JS only. |
Beta Was this translation helpful? Give feedback.
-
I do strongly disagree that if someone updates it anyways that it is a plus. I agree though that there is benefit to showing features within a game.
To the extent they are out of date - they ought to be deleted. We are not rich time-wise on this project. If it takes 4 hours to find what is out of date to delete only that, then deleting everything IMO is a better move so we can spend the time elsewhere. That is one thing TripleA could be better at, DELETING out of date documentation. tvleavitt stated well, documentation is either accurate & up to date, or it is deleted, nothing in between. If PoS is no longer the reference doc, then the comments are best migrated and/or removed. If it's even worth the effort to do that, I'm not fully sure. Though, cleaning up loose ends is a great thing to do, and someone probably will stumble on PoS as a reference document at some point.
I will quibble here: (1) the resistance to using the pencil icon in github to use a web browser text field to update a file - I have been shocked/surprised at the level of resistance. If you say "github" in the current map making forums, you're more likely to get into a flame war at this point than anything productive. It's unmerited and perhaps ignorant IMO. Be what it may, you're not going to get a lot of love when you say something can be updated via the Github website. In the case of PoS, that is a barrier. (2) lay people do not update the reference XML. The Triple-A XML is tightly mapped to the code (largely for worse), meaning updates to the reference file usually follow updates to the code. The two points taken together, it's only maintainers that update the PoS XML. The last update to the map file was 4 years ago, the history is dominated almost exclusively by maintainers: https://github.com/triplea-maps/the_pact_of_steel/commits/master/map/games/pact_of_steel_2.xml?before=be0efc7042287dd24a2bbb57e5bc01f4fe4fe5d7+35
Updates to files hosted in github are that easy. Open a web page, click a button, edit the text, and then click "create pull request" instead of "save." I do agree though that there needs to be an ease to make the updates. To this extent, you may have seen the forum post where I pitch the idea that we find and adopt a wiki to help solve some of these documentation problems. Though, the XOB seemingly can't be hosted on a wiki as the content is dynamic. Nonetheless, easy to update is still a goal. I think we will have that, as it'll be a single file that needs to be updated. |
Beta Was this translation helpful? Give feedback.
-
Sorry for repeating, but I'm not sure if the concept has been overlooked. As I said, just update PoS2 clearly as to state that it is not any longer the main reference. So long as that is clarified, leaving them be is obviously no worse than deleting them (because anyone can read the warning and choose not to read anything). If anyone is so careless as to ovelook a well displayed warning, it's his/her fault. I don't see any problems especially in the moment they are just the comments within some game (once it is no longer a TripleA reference). |
Beta Was this translation helpful? Give feedback.
-
|
Slightly out of date can be worse than completely out of date documentation, and in both cases it's arguably worse than no documentation at all.
I think the question is really - what's the real benefit of having the documentation commentary in that file? Consolidating that info into the XML browser is probably the best move I believe. The 'rule' of "update documentation or delete it" I don't want to debate. Not deleting, not consolidating documentation - and instead the various parts of the communities not finding documentation and re-writing it - I think those are key parts to how we got into a bad situation. Bottom line though, it's going to take effort to do something with PoS XML file; whatever we do is likely going to be better than leaving it to atrophy. Another stray thought, since Git never deletes anything (Git & Github are NOT the same thing at all) - we could put a link to a historical version of the XML file if we really wanted. But again.. if someone wants documentation, then we are probably best off investing in a real documentation solution, and have the person look there (rather than potentially wasting time in multiple older documentation sources) |
Beta Was this translation helpful? Give feedback.
-
|
The only thing of PoS2 which will need to be rewritten is this comment:
For example, changing the phrase "how to use all the features" to "how to use many of the features" and such. |
Beta Was this translation helpful? Give feedback.
-
I propose we add the XML option browser to the repository.
For reference, this is what I'm talking about:
https://forums.triplea-game.org/topic/729/xml-option-browser?page=1
http://www.starlords3k.com/XOB.html
The main advantage would be that we could keep it up to date with changes. It's already a bit out of date, since it hasn't been updated with recent changes.
I had tried to contact the author for a few times to see if he could officially bless this, with never any reply, but then I just re-read his forum posts and saw this post:
https://forums.triplea-game.org/topic/729/xml-option-browser/8?_=1715551370156
To me, that seems good enough as permission to upstream it.
Beta Was this translation helpful? Give feedback.
All reactions