New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Help - Move from .chm to a new format #437

Closed
tomcw opened this Issue Jul 19, 2017 · 11 comments

Comments

Projects
None yet
4 participants
@tomcw
Contributor

tomcw commented Jul 19, 2017

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

This comment has been minimized.

Show comment
Hide comment
@sicklittlemonkey

sicklittlemonkey Jul 19, 2017

Contributor

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.

Contributor

sicklittlemonkey commented Jul 19, 2017

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

This comment has been minimized.

Show comment
Hide comment
@tomcw

tomcw Jul 20, 2017

Contributor

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.

Contributor

tomcw commented Jul 20, 2017

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

This comment has been minimized.

Show comment
Hide comment
@tomcw

tomcw Jul 20, 2017

Contributor

Reordered batch file:
AppleWinManual.bat.txt

New PDF:
AppleWinManual.pdf

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

Contributor

tomcw commented Jul 20, 2017

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

This comment has been minimized.

Show comment
Hide comment
@tomcw

tomcw Jul 22, 2017

Contributor

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.

Contributor

tomcw commented Jul 22, 2017

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

This comment has been minimized.

Show comment
Hide comment
@Keatah

Keatah Jul 22, 2017

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.

Keatah commented Jul 22, 2017

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

This comment has been minimized.

Show comment
Hide comment
@sicklittlemonkey

sicklittlemonkey Jul 23, 2017

Contributor
Contributor

sicklittlemonkey commented Jul 23, 2017

@Michaelangel007

This comment has been minimized.

Show comment
Hide comment
@Michaelangel007

Michaelangel007 Jul 27, 2017

Contributor

👍 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. ;-)

Contributor

Michaelangel007 commented Jul 27, 2017

👍 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

This comment has been minimized.

Show comment
Hide comment
@tomcw

tomcw Aug 4, 2017

Contributor

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 having installed alternate unzipping software (eg. 7-zip).

Contributor

tomcw commented Aug 4, 2017

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 having installed alternate unzipping software (eg. 7-zip).

@Keatah

This comment has been minimized.

Show comment
Hide comment
@Keatah

Keatah Aug 4, 2017

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.

Keatah commented Aug 4, 2017

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

This comment has been minimized.

Show comment
Hide comment
@sicklittlemonkey

sicklittlemonkey Aug 4, 2017

Contributor
Contributor

sicklittlemonkey commented Aug 4, 2017

@tomcw tomcw closed this in fb96314 Aug 14, 2017

@tomcw

This comment has been minimized.

Show comment
Hide comment
@tomcw

tomcw Aug 14, 2017

Contributor

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

Contributor

tomcw commented Aug 14, 2017

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

@tomcw tomcw added this to the 1.27 milestone Aug 14, 2017

@tomcw tomcw added the enhancement label Aug 14, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment