Moving Reference Guide to Wiki

Development
1

I’ve started the process of moving our Reference Guide to the wiki. It will probably take me a couple of weeks to port it over.

Having our reference guide in a wiki will have the advantage of making it easy for anyone to update the documentation, keeping it accurate and in sync with the latest version of VASSAL.

Once the project is done, we might want to consider changing the VASSAL distribution so that it no longer ships with HTML but rather points to the wiki.

I am working from the HTML Reference Guide that ships with 3.1.14. Is this the most up-to-date version of the docs? I recall reading in the forums that someone was working on updating the guide–I wouldn’t want my work to get out of sync with this initiative.

P.S. I’m using the perl tool html2wiki to do most of the heavy lifting, then doing a bit of automated post-processing on my own.

2

Thus spake fil512:

Once the project is done, we might want to consider changing the VASSAL
distribution so that it no longer ships with HTML but rather points to
the wiki.

I see two problems with this:

  1. It’s nice to have access to reference materials off-line.

  2. If the RG in the wiki follows the current version of VASSAL and
    something changes, where will people find the version of the RG for
    older versions?

–
J.

3

Good points.

At a certain point, my hope is that the wiki version of the docs will be of significantly higher quality and accuracy than the HTML docs we have now. Could we generate the HTML that ships with VASSAL from the wiki pages somehow?

-K

4

Thus spake fil512:

At a certain point, my hope is that the wiki version of the docs will be
of significantly higher quality and accuracy than the HTML docs we have
now.

I think that won’t take long.

Could we generate the HTML that ships with VASSAL from the wiki
pages somehow?

I’m sure there’s a package in CPAN which will do it, if MediaWiki can’t
do it itself.

–
J.

5

FYI the Reference manual is now completely converted to the wiki.

Some of the wiki formatting doesn’t look good (e.g. I don’t like what it did with H4s–translating them into grey boxes with small courier font). And some of the widths look off. But by and large I think it’s functioning.

Next step is to start bringing it up to date with the current Vassal engine. I’ll spend some time doing that in the coming weeks.

Ken

P.S. After I ran the html2wiki script to convert the html to wiki format, I hired my 13 year old son for $25 to copy/paste all the pages and images up to the site…

6

If any of you feel inclined to help clean up some of the formatting for us, we’d all be much obliged!

7

Correction: I just noticed that my son missed a few pages and images. I’ll post again when I think he got them all.

8

By the way, if you see a grey box around a block of text in courier font, I discovered it’s because there is a space at the start of the line. This is an artifact of how the HTML got translated into wiki. If you see one of these, you can fix it by deleting the space at the start of the line.

-K

9

The Reference Guide is now completely moved into the site wiki.

10

Thus spake fil512:

The Reference Guide is now completely moved into the site wiki.

Wonderful. Thank you.

–
J.

11

The Reference Guide is now completely moved into the site wiki.

Excellent work. But the the need to be able to export/convert the wiki into either HTML or PDF is pretty vital. Be careful about making drastic changes until we are sure we can generate an off-line manual automatically.

B.

12

B,

I’m very confident that any number of standard web site spider programs will be able to walk the site and produce the HTML and images needed to render the documentation offline as a set of web pages as it is now. The documentation is presently structured as linked web pages–I’m not sure how well it would translate to PDF–probably not worth the trouble.

-K

13

I’m very confident that any number of standard web site spider programs
will be able to walk the site and produce the HTML and images needed to
render the documentation offline as a set of web pages as it is now.
The documentation is presently structured as linked web pages–I’m not
sure how well it would translate to PDF–probably not worth the trouble.

I’m quite confident that you will find a tool to do this also, there are many, many listed on the Mediawiki Alternative Parsers page. I am less confident that you will find a tool that will be easy to use and produces something that looks good.

I don’t want to be overly negative, but if I was you, I would make that my first priority to see exactly where we stand.

Cheers,
B.

14

Thus spake “Brent Easton”:

I’m very confident that any number of standard web site spider programs
will be able to walk the site and produce the HTML and images needed to
render the documentation offline as a set of web pages as it is now.
The documentation is presently structured as linked web pages–I’m not
sure how well it would translate to PDF–probably not worth the trouble.

I’m quite confident that you will find a tool to do this also, there are many
, many listed on the Mediawiki Alternative Parsers page. I am less confident
that you will find a tool that will be easy to use and produces something th
at looks good.

I don’t want to be overly negative, but if I was you, I would make that my fi
rst priority to see exactly where we stand.

I’ll see about this soon, but I’m not sure I’ll be able to get to it
before I come back from Portugal next Saturday.

–
J.