Bug: a88/4a299

(no content)

Have added a draft manual file to the repo to serve as an occasional
brain-dump for things that need to be in the documentation.

Would JavaHelp be the right thing to use for displaying the
documentation? Could just do it in HTML and put it online, but users
may want to read it offline.

JavaHelp looks a little heavyweight -- even the jhbasic jar is ~400kB,
around twice the size of PuffinPlot! What about writing docs in
AsciiDoc or similar, putting HTML version online, and providing
HTML and PDF versions for download?

AsciiDoc looks promising actually -- can generate chunked HTML via
DocBook. Processing will obviously be a bit heavyweight since it needs
a DocBook toolchain, but output shouldn't be too big.

With Batik now bundled, size is less of a concern for JavaHelp,
and there is a full HTML manual produced using htlatex. The only 
remaining thing is the work of actually integrating the JavaHelp
classes, producing the JavaHelp files from the HTML, bundling
them into the jar, and persuading JavaHelp to load them. JavaHelp
seems to be fairly old, seldom used, and with limited documentation,
so I'd estimate this at maybe 8-16 hours of work.

JavaHelp appears to be dead -- last release in 2007, last commit in
2011, mailing lists dead for years. The possible replacement, Oracle
Help, has rather murky licensing terms which seem unlikely to be GPL
compatible. In any case, with an extensive HTML and PDF manual now
provided both for download and online reading, adding an extra built-in
manual seems like a poor use of time. I'm closing this as "fixed" on
the basis of the existing manuals and in-application tooltips.