Editing the Reference Manual

[shilinski]

I was wondering how I can edit pages in the reference manual. Sometimes the information is incomplete, so I must run test cases to get the straight dope. I’d like to fill in the missing information in the online documentation.

I noticed that I can do it via the Wiki, but I wondered if the Wiki reflects the current official documentation. If I change a page in the Wiki (e.g. the “rotate” trait), am I wasting my time with regard to the official documentation?

[JoelCFC25]

As I understand it, all the documentation (reference manual, designer's guide, user's guide) has been transitioned to Asciidoc format and put in the Github repository (specifically here) with the rest of the project for easier long-term maintenance.

With a Github user account you can fork the repo to your own copy, make edits in your own copy, and submit them as pull requests to the master. There's an extensively-detailed guide to getting the whole project built by replicating to a local machine for doing development, but for doing edits to documentation you might find just doing the editing right within Github itself is easier and quicker.

[Brent Easton]

Hi Stan,

That would be FANTASTIC if you could work on updating the documentation. As Joel mentioned, the documentation to work on will be the online documentation stored in github. We generate both the internal Vassal documentation and the stand-alone PDF guides from this source. We also have it on the list to generate either the Wiki pages, or some other online web resource from this source. Updating the wiki directly is a dead end.

One really 'fun' job that also needs doing will be to update all of the Dialog screen-shots in the reference manual as the dialog layouts have changes substantially in 3.5.0-beta 1 and will change again subtlety in 3.5.0-beta-2. (Just in case you need to make any screenshots).

As Joel mentioned, the easiest way forward is probably to make your own fork of the repository and then edit that fork directly in github. However, that only gives you a simple text edit of the source docs. You may want to edit the files using a proper AsciiDoc aware editor outside of github. Jump on the Discord server and we can chat about it.

Cheers,
Brent.

[shilinski]

First off, I do not intend to update the reference documentation as a personal project. Right now I’m building modules so I can play euros with my usual partner COVID-safely and solo as a bonus. I ask myself is it worthwhile for me to take a timeout so I can study and learn the ins and outs of github. I think not. It would make sense if I decided to dive into the documentation as a whole but not for on the fly updates.

For example, I needed to use a property for the Rotate trait so I could “un-rotate” a piece back to its starting state. The property, according to the docs, is <name>_Facing. “Name” is the name expressed “above,” and facing is facing. The trouble is there is no “name” field above. It’s either “description” or “command,” but which? And facing. Is it a number? Is straight up 0? 1? Something else? So I’m forced to run a test to get the straight dope, but 6 months from now I’ll have to do it again because I won’t remember the answers.

This is what prompted my question. Before anyone answered, I jumped into the wiki and updated the docs for Rotate and two other traits, and voila! They got inserted. Easy-peasy, done. This means the dead wiki might end up being my personal ref docs. Since no one else will probably look at it, I can even add personal commentary such as the steps needed to un-rotate a piece. I imagine this horrifies you, Brent, but I’m not about to take a course in github, so it’s either the wiki or nothing for me. Sorry.

[Cattlesquat]

Just to be clear -- the wiki reference manual pages having been mostly inactive years, the extra details that *were* there have been scraped into the VASSAL reference library (the "adoc" files) as of the transition from 3.4 to 3.5, and the intent is that at some point, possibly in the near future, the wiki will be wiped/replaced with this material.

In other words, it is probably a mistake to attempt to add significant content to the "Reference Manual" section of the wiki at this time. We hadn't thought any particular amount of announcement about this was in order given that the wiki reference manual had been completely inactive for years, but anyway there it is. If there were some useful extra bits that got over into the wiki before this became widely known, we may see about bringing them over, but we don't propose a continued program of merging nor maintenance.

Meanwhile editing the much-more-active-and-useful files is actually quite simple -- you can go here: https://github.com/vassalengine/vassal/ ... enceManual and there they all are, ready to be browsed and edited. This is the ONLY form of the reference manual that is likely to persist in existence into the future.

Best,

Brian