Are the (HTML-based) Reference Manual and the (PDF) Designer’s Guide generated from the same ASCIIdoc source, or are they separate entities? I’m asking because I’ve noticed that the Designer’s Guide PDF seems to have nothing about BeanShell included (it doesn’t list the Calculated Property trait, either)…
No, they are two separate, unrelated sets of ASCIIdoc source and png images.
The designers guide was developed by a Vassal user some years ago and has had little maintenance since. As you can see, it is woefully out of date in some areas. I’ve committed to bringing the Reference Manual up to date, but do not have the time to spend on the Designers Guide.
It is possible to create a new branch, edit and update the documents and images and push a PR directly in the Github web interface if that was something you would be interested in taking on?
I’m actually wondering if it would make more sense to just combine them into a single entity. Does the Designer’s Guide include anything useful that isn’t in the Reference Manual? (I need to properly compare the two, I guess…)
I would prefer not to.
The Reference Manual is straight, these are the options, this is what the options do. We link directly into it from the Editor Help system.
The Designer’s guide is a Fan developed document that makes judgement decisions on how you might use those options to achieve different goals. It covers information that is outside the scope of the reference manual
However, I think there is scope for the Designer’s guide to be substantially redesigned and reduced in size. It duplicates a lot of the Reference Manual information that it should really link to instead. Just retain the touchy-feely stuff, and re-direct to the reference guide for the detailed stuff. Of course, that doesn’t work so well as a stand-alone PDF document. This is the stuff we wanted fans to build in the Wiki, but it never happened.
The Designer’s guide might perhaps be better as a set of stand-alone ‘Articles’ that discuss different aspects in depth?
‘Getting Started’, ‘Creating your Hello World’ module, etc. I’m not sure.
I’ve been using the Designer’s Guide to look up things that I should have been looking for in the Reference Manual–partly because I didn’t realize only the Reference Manual was truly up to date, but also because it’s easier to search for specific things in a PDF than in a linked series of HTML documents.
I think it would be a good idea to strip out all the redundant and old stuff from the Designer’s Guide and point people to the Reference Manual, instead, to avoid confusion. I suppose I can make that my project if no one else wants to do it…
It should be possible to both
a) Include a page-based version of the Designer guide within Vassal to allow for links to the reference guide to work.
b) Generate a PDF version of the Reference Manual. It just needs a suitable front-page loading all of the sub-pages in a suitable order and generating a TOC.
Or even a combined PDF containing both.
I use both, but I find the Designers Guide (old as it is) - is my go to / first-look source to figure stuff out…
I definitely second the notion that it’s very helpful to have PDFs of this stuff… I use PDFs all the time, including locally saved copies when I’m disconnected…