[Request] Help files

[brickviking]

I took a quick look inside the EducationCentre7.hmxz file, and saw a couple of anomalies in the text I'd like to correct. Do you want me to explode that file into its own folder, add them to my git fork and work on the raw XML files there, or simply rezip the file once I'm done so you can import it into that Help and Manual tool you're using?

One of the things I was thinking of was to trim most/all references to "Only in Dolphin Professional" and slightly edit the "Professional Edition Summary" to update it from the X6 era. Aside from that, I would probably just add the missing descriptions (Chunk Browser) for stuff in Additional Tools and Sample Files.

Let me know what you think.

[blairmcg]

I don't know that the help tool can/will be run again (I don't have it), so there probably isn't much value in preceding down that path.

[brickviking]

Hm. Okay, what else can we "make" chm files with? I'm also on Linux so I have some XML conversion tools here, but I suspect most of the Windows tools are "hey man, pay man" tools. Sigh. The more we work with Dolphin, the more the documentation should be up to date with the latest(ish) version. It's not too bad currently, but I'd like to help keep it that way.

In addition, what should we do about the popups file, which would no longer work under Win10? I've managed to get them to work on Vista just by copying the popups6 .hlp file to popups7; that got me most of the items popup text, but tends to fall on its nose on stuff that's not in the popups file (Chunk Browser and others).

The other option is that we could bring popup help display in-house and replace the OS call for the popups, so to speak. It'd mean we'd need to create the windows, fill them with text, and pretty much do what displaying entries from a .hlp file does, but within smalltalk instead of farming it off to the OS that no longer supports it. Would that be a lot of extra work?

Roughly:

• Watch for Shift-F1 key (already in image, calls whatsThis: )
• Capture icon—or folder—under pointer at the time of the Shift-F1 (already in image)
• Replace the external syscall with the steps below:
  • Create window
  • Fill with relevant text, and run expose.
  • Wait for mouse button event or keyboard event
  • Destroy window

Is there anything more I'm missing from that list?

[blairmcg]

This kind of in-product help was considered necessary for commercial offering at the time, but even if it were still a commercial product I think one would put the help online today. Whether that is worthwhile use of very limited available effort is uncertain. I am more certain that I don't want to spend my own time on it though.

[brickviking]

Help and Manual (Professional) isn't available to me either, certainly not for the €598 they want. Even Basic still costs €399 exclusive of VAT/GST. Did Andy (or others) happen to know what happened to that particular license that they must have had?

Anyhow, I have some options I was thinking about regarding the help file.

• we don't update it at all. It's mostly fine as it is. I'd rather not go down this route.
• we keep it as a standalone file, but we update it to current state of play for Dolphin.
• we host it online in some fashion and update it, whether wiki or simply a web-ised version of the .chm/hmxz,
• we do both (online with offline backup), allowing for the fact that some businesses will prefer to run offline where feasible.

I hear your point about not wanting to spend your own time on it, given that you've probably got little enough spare time as it is. I think I can do justice to the job, as I've got a decent amount of time. I've also explored enough of the document whereby I think I can make some changes that won't break things; I'll just need to check the original XML files into a branch so we've got something to work with at least. Getting those into a form that we can use—whether online or offline—will be the next big challenge.

[brickviking]

I've been doing a bit of work on the Help files, I've got most of the mistakes cleared out that I found, and have rewritten several phrases to better reflect the original author's intent (or so I hope). What I don't have is a way of getting "pretty" output, though I do at least have HTML output working. Should I just use the framework files (the js and html framework) that H&M uses? They do work after all. The only thing I don't know about that is would I be treading on potential copyrights for the H&M material being included?

I've also set up a document at my fork in the wiki Help Discussion which lists my thoughts on the matter. Would you like to contribute any further thoughts?

My work is available at my fork for perusal. I'm also not 100% sure how well my toolset would transition to a Windows environment, I'm aiming more at a cross-platform solution, at least for the documentation. If it can be accessed by the Visual Studio build tools as well as being cross-platform, so much the better. I'd still like to be able to generate a .chm for those organisations that want to run this offline.

[rjk100]

I think in-product and up-to-date help is essential and really appreciate anyone's efforts in that direction.

I believe you can ignore the EducationCentre7.hmxz file which is used by the commercial program and just use the chm help file itself. To that end perhaps the following may be helpful:

On Windows 10:

1. Download Microsoft Help Workshop from https://docs.microsoft.com/en-us/previous-versions/windows/desktop/htmlhelp/microsoft-html-help-downloads and install it.
2. Double click on EducationCentre7.chm to view it in the Microsoft Help viewer. If you cannot see the contents in the right pane, ensure the Dolphin help file is not blocked by right-clicking on EducationCentre7.chm and select Properties. If you see an "Unblock" button click it and save.
3. Run hhw.exe (the HTML Help Workshop program you loaded in step 1).
4. Select File - Decompile from the menu.
5. In the resultant dialog, select the Destination folder (where all the html files will be extracted) and enter EducationCentre7.chm as the Compiled Help file.

You now have html help files for all of the chm file (which could be used as the base for a future HTML-only help system) or you can just use the Help Workshop to update and compile new chm help files.

[brickviking]

I think I've effectively done as much with the workflow I built, only I'm working with what appears to be the original XML files that make up the project, and rendering them out to HTML as I need them. I'm still a bit lost when it comes to the framework that I'll end up displaying the help pages in, and my HTML-fu isn't great.

I had thought seriously of using the original files that were supplied with Dolphin, but I have a funny feeling that there might be some IP involved from Help & Manual, so I'll be looking to replace that with something else, maybe even rolling my own.

[rjk100]

If there are IP concerns I would think they would be restricted to the proprietary EducationCentre7.hmxz file format used by “Help and Manual (Professional)” and not to the help content EducationCentre7.chm that was presumably created and generated from it by Object Arts, but IANAL. I assume the actual help content is the same in each file.

My post above explains how to use a freely available program (Microsoft HTML Help Workshop) to extract all the help directly from the .chm file as HTML files. The HTML files can then be updated and used as required. The same program could generate an updated .chm file to include with Dolphin if needed. To me this seemed more direct and easier than manipulating XML files extracted from the proprietary .hmxz file. Regardless, your efforts are appreciated.