Help - Move from .chm to a new format

[tomcw]

Spun of from #436.

Tom, maybe we should consider moving to a different help format. What do you think?

Yes. Perhaps the simplest thing to do is just ship the html (and png) files and for the Help button (F1) to just open the toc.html in a browser.

NB. Currently from toc.html it's not possible to navigate to all parts of the help... ie. more TOC items need adding.

[sicklittlemonkey]

Yes, the more hyperlinking the better.

The other alternative that would still keep the hyperlinks is converting the HTML docs to a PDF. That way there's just one file.

One easy way to do this is with:
https://wkhtmltopdf.org/

I've attached a simple test below. I've used this before but not extensively, so there are probably better ways. For instance it can generate a TOC, but I've just used our existing one - though content is imported in the order you supply the file names, so I've put toc first.

There are some other ideas here:
http://explicate.blogspot.com/2011/01/multiple-html-files-to-single-pdf-with.html

There are also other programs that wrap wkthmltopdf with more functionality, e.g:
https://github.com/cloudify/sPDF
https://github.com/pdfkit/pdfkit

Here's a batch file I threw together. Would be better to do this in PowerShell perhaps.
AppleWinManual.bat.txt

And here's your new AppleWin Manual!
AppleWinManual.pdf

Cheers,
Nick.

[tomcw]

Hi Nick,
Wow! Looking good : )

though content is imported in the order you supply the file names, so I've put toc first.

OK, so I just need to reorder the input of the pages and then the PDF will read in the right sequence.

I have no problem in switching from CHM to PDF though.

[tomcw]

Reordered batch file:
AppleWinManual.bat.txt

New PDF:
AppleWinManual.pdf

I'll check this into git, and switch to PDF in the zip distro.

[tomcw]

Another alternative (to PDF) is just to move all the help online and host (as HTML / wiki) on github, eg:
https://github.com/cc65/wiki/wiki

A (small) advantage is the separation of the help from the main release so that you can update the help without needing to do a new release (not that we've ever needed to do this).

Equally this is a disadvantage, since the online docs will only match the latest AppleWin release, so if you are running an older version, then you won't have access to accurate docs.

Anyway, the PDF is dead easy to generate, so let's switch to that.

[Keatah]

I thought the original chm file worked well enough. But I suppose if a change has to be made, then PDF would be the next choice as opposed to online browser-accessed help.

Several other programs I work with went the online-html route for a while and came full circle back to locally saved chm/pdf/doc files.

[sicklittlemonkey]

All versions can still be generated. It's just a question of what we distribute. There's still the option of getting and using the HTML files locally, or maybe even merging them into one HTML file with something like this: https://sourceforge.net/projects/htmlmg/files/ Cheers, Nick.

[Michaelangel007]

👍 PDF :-)

Would have preferred markdown, but the PDF output looks good enough.

Just took a look at the batch file -- it reads the source HTML file so I'm happy. ;-)

[tomcw]

Nick - given the recent discussion about ADS on csa2p, see this thread: "ProBLOAD (a DOS 3.3 tiny extension)". this is exactly how the AppleWin.chm is blocked.

So all we need to do is delete the AppleWin.chm:Zone.Identifier ADS.

We could do this each time AppleWin is run (obviously it only needs to be done once, but AppleWin has no memory of if it has been run before; also it doesn't cause a problem to delete a non-existent stream).

Also it's simple: the standard DeleteFile() Win32 API function supports this:
DeleteFile("AppleWin.chm:Zone.Identifier");
Ref: http://www.flexhex.com/docs/articles/alternate-streams.phtml

So should we just stick with CHM's and apply the above DeleteFile() fix?

NB. I downloaded an AppleWin.zip (from github applewin), and it has the ZID ADS. When I extracted using 7-zip, then the ADS was not applied to AppleWin.chm. So I assume only users that use Windows' built-in zip support get the ZID ADS attached to their AppleWin.chm file (or they have directly downloaded it from the web, eg. from the github applewin repo).

EDIT: (14/8/2017)
I restored the default Win7 .zip file association with Explorer. Browsing within the zip (via Explorer) all the files inherit the ZID ADS. Attempting to launch AppleWin.exe results in a message saying you need to extract and suggests a folder to extract to. When you accept this, then again all files in this folder have an ZID ADS. So this issue is only affecting users that haven't installed alternate unzipping software (eg. 7-zip).

[Keatah]

For what it's worth I strongly prefer the .CHM help file format. As do some of my colleagues.

Killing or otherwise setting the ADS to something else is a good solution. If and when I have "chm troubles" I usually right-click and select "unblock" and all is well. That on windows os.

[sicklittlemonkey]

CHM seems like a legacy format to me, but I'm neutral on the decision. If users prefer CHM then it's worth trying it. Cheers, Nick.

[tomcw]

fb96314 - "At the point of opening AppleWin.chm, try to delete any Zone.Identifier alt data stream"