Technical questions

[uckelman]

Thus spake Flint1b:
> 1) The Vassal documentation (Users Guide, Module Designers Guide) pdfs
> are from Vassal version 3.1, they are hopefully written in latex, is
> their source available and can it be put up on github, and included in
> the release process?

* The Reference Manual is some _very_ old HTML, in doc/Reference Manual.

* The Users' Guide is a Word document in doc/userguide.

* The Module Designers' Guide... is not in the repository and might take
a bit of tracking down, but IIRC it's also a Word document.

I argued at the time that both the Users' and Module Designers' Guides
be done in a format which was diffable, or otherwise they'd be impossible
to maintain... and here we are. I didn't press for doing them in LaTeX,
though that was my preference, because I was the only one at the time
who knew LaTeX. Something like Pandoc or even HTML5 would have been better
than Word.

(Can anyone point out where the source for the Module Designers' Guide
is?)

All three of these need updating for 3.3.

--
J.

[Flint1b]

I argued at the time that both the Users' and Module Designers' Guides
be done in a format which was diffable, or otherwise they'd be impossible
to maintain... and here we are. I didn't press for doing them in LaTeX,
though that was my preference, because I was the only one at the time
who knew LaTeX. Something like Pandoc or even HTML5 would have been better
than Word.

Asciidoc is often used in the Java world, and Pandoc is a neat swiss army knife that could convert the Word documents to Asciidoc https://asciidoctor.org/docs/migrating-from-msword/, then we could use the Asciidoc maven plugin to generate PDFs as part of the build https://asciidoctor.org/docs/asciidoctor-maven-plugin/.

[Flint1b]

I tried to convert the userguide.doc to Asciidoc using Pandoc, the result is ok, it needs to be cleaned up a bit but everything is there, the text, the paragraphs, headers, the images.

If there is interest in maintaining the guide, I would prepare a PR which adds the necessary files and maven build steps. I would prefer to add this as a separate maven module though so it's best done if/after we PR #57 which switches to maven-multi-module.

If the sources for the module designers manual are found, we could do the same for it as well.

The reference manual seems to exist twice, once as html in the code and a second time on the wiki, we could change it so there is only a single source, probably best to keep it in the code and add a step to the release build which updates the wiki pages, e.g. with https://github.com/fastily/jwiki.

[Cattlesquat]

Hmmm, is there a solution where the master guide becomes the Wiki and then gets slurped up occasionally into a manual for release?

Because the Wiki offers the opportunity for crowdsourcing of some of the best knowledge, AND offers a more tried-and-true way of maintaining a body of information where the knowledge is distributed over a bunch of people.

Speaking of the Wiki I would also love to see us create (as many sites do) a level of privilege below "admin" but above "joe schmoe" -- e.g. Expert or Veteran or whatever, and the main important privilege would be posting wiki edits without the moderation cycle (in other words, equal to a "normal user" on most wiki-based sites). I gather the moderation was put in place mainly because of bots, so having a normal wiki level of trust conferred on long-time users doesn't seem like a big risk. I edit the wiki occasionally but it feels sort of like "editing through molasses" and so I don't end up contributing nearly as much as I otherwise would.

[Flint1b]

Hmmm, is there a solution where the master guide becomes the Wiki and then gets slurped up occasionally into a manual for release?

That would be good too, sometimes we used confluence wiki at work to write the main documentation, then export it to PDF. Not sure of mediawiki has this, but it probably does.

[Flint1b]

I will probably get rocks thrown at me for asking this, but after being involved with the code for couple months I feel I have to ask.. What's the deal with these "key commands" or "global key commands" or "GKC"s, I see a lot of discussions where these are involved, I have seen how the modules have a hotkey for each and every possible action, I have never used them in any of the modules I play since it's more convenient with the mouse.. Why are these key commands such an important topic, is the whole application glued together by real and virtual key commands being sent back and forth??

[Cattlesquat]

Key Command is really just a legacy name from A Time In Ages Past when Vassal worked exclusively on key commands. I think even THEN, the key commands also generally had ways to perform them with the mouse (e.g. from the context menus). And THESE DAYS there don't even have to be "actual keys" associated with "key" commands, you can just name it something like DoTheAxisThing which is sort of the Vassal evolutionary equivalent of being able to name a memory location with a "name" rather than 0xe458:0x3200 and stuff like that.

So really a "key command" is just a "command" that activates an individual Trait (to you, Decorator) of a Piece (to you, GamePiece), and makes that trait "do a thing", whatever that trait likes to do when it gets the right signal. And a Global Key Command is a KIND of trait (for once the internal Java code name is the same) that applies a "key command" to all the pieces on a map (or all maps) that match a certain filter. So they're a powerful building block of modules (since they are almost the only way two different GamePieces can affect each other), but they're also a big performance hit because every GKC has to first build a list of all the maps it can touch (that's the easy part), THEN, for each map go through every *piece* on that map and see if it qualifies (matches the bsh expression filter) to receive the command, and finally for each piece that matches the key command goes through and checks every single Decorator ("trait") in the piece to see if it happens to be fired off by this "key stroke" (which might just be a "named key stroke" which is the kind of key stroke that isn't actually a keystroke, like I mentioned earlier), and if it does match, then fire it off.

p.s. GREAT place if you can find any optimizations! I also dream of a future world where we maintain a list of pieces in each Zone (and maybe even in each Region) of a map, so that we could have "Zone Key Commands" and/or "Region Key Commands" and have them run faster because they don't have to process through every piece on the map -- because honestly MOST of the time I fire one of these I actually already know a specific sub-region of the map that I care about. As long as maintaining those lists wouldn't be a cure worse than the disease, of course. We had a little linked list for every single "square" in Civ2 though, so I know it's at least in the range of possibility.

[Flint1b]

Good explanation, thanks a lot.

First thing that comes to mind is to use the stream API's Collection.parallelStream() to process all pieces in parallel.

[Cattlesquat]

Any time! It's the least I owe you at this point