Author Topic: Best way to add extra help (.chm) files?  (Read 1596 times)

Monsieur OUXX

  • Mittens Half Initiate
    • I can help with proof reading
    • I can help with translating
    • I can help with voice acting
Best way to add extra help (.chm) files?
« on: 13 Jun 2012, 12:02 »
I'm currently trying to imagine the best way to integrate the help of plugins/modules/parallel editor branches directly into the AGS editor.
At the moment, AGS' help is based on the old Windows ".chm" help files.
A quick look at the Editor's code shows that opening the help simply creates (or focuses on) an instance of the help file shipped with AGS.

I was considering 2 leads :
1) Decompiling the .chm file, adding the plugin's index and articles, then re-compiling it. It's not too hard in theory, even though the .chm format and tools are awfully badly documented, and not really easy to handle through command line (the "HTML Help Workshop" tool is obviously primarily targeting WYSIWYG rather than automated treatment).
- The only drawback I see here is the need of using an installer that would explicitly run that task. Not everybody likes installers or .bat files.
- Also there would be a risk of corrupting/saturating the original AGS help file after installing many plugins. Obviously, if I choose that method, I'd create backups of the original .chm file, and I'm assuming that someone who installs plugins is not too demanding regarding the consistency of his AGS help file (he knows what he's doing and is not afraid to revert to the backup).

2) Create an Editor plugin that would allow the handling of several, independent help files. I don't know if that's possible without an extensive modification of the code. In particular, it would be hard for the Editor to decide what file to open when the developer highlights a word and presses "F1", as it would have to scan the index of each .chm file first.

Does anybody have suggestions?
This topic could also be the occasion of discussing a potential migration of the help system to more modern and flexible technologies -- like plain HTML files open in a browser, for example, but still with an index and search capability.


EDIT: Damn, this .chm format is a mess. The good news is that MS provided a simple chm-files merger for public use (use the compiler hhc.exe with a .hhp file that contains a [MERGE FILES] section, as described here). The bad news is that hhc.exe crashes on Windows 7 :-) All the third-party mergers I've found so far seem to be just UIs making the use of hhc.exe more intuitive (no open source stuff, unfortunately). However I've tried a free utility called "ABC Amber CHM Merger" and hhc.exe didn't crash. I'm puzzled.
« Last Edit: 13 Jun 2012, 14:43 by Monsieur OUXX »
 

Snarky

  • Global Moderator
  • Private Insultant
    • Best Innovation Award Winner 2018, for his numerous additions to the AGS open source ecosystem including the new Awards Ceremony client and modules
    • I can help with proof reading
    • I can help with translating
Re: Best way to add extra help (.chm) files?
« Reply #1 on: 14 Jun 2012, 08:09 »
It seems hhc.exe needs to be run as an admin on Win7. Did you try that?

Monsieur OUXX

  • Mittens Half Initiate
    • I can help with proof reading
    • I can help with translating
    • I can help with voice acting
Re: Best way to add extra help (.chm) files?
« Reply #2 on: 14 Jun 2012, 09:13 »
It seems hhc.exe needs to be run as an admin on Win7. Did you try that?

Yep, first thing you need to try of course :-)
Actually I put it inside a .bat and then ran the .bat as Admin, but I'm never sure if the privileges are propagated to children-processes in Windows shell.

EDIT: It seems to crash only with a .hhp project for [MERGE FILES]. A normal compilation seems to work fine.

EDIT2: Still waiting on suggestions, people.
« Last Edit: 14 Jun 2012, 15:24 by Monsieur OUXX »
 

tzachs

  • Parking Goat- games that goats like!
    • I can help with translating
    • tzachs worked on a game that was nominated for an AGS Award!
Re: Best way to add extra help (.chm) files?
« Reply #3 on: 15 Jun 2012, 15:59 »
I think it should be in separate help files (option #2).
Having it all in one help file is too much of a fuss and makes less sense to me.

Also, I don't think it requires a plugin, I think we need to add the feature to the editor.
When exporting a module/plugin, export a help file as well (maybe extract from the script comments).

Add a menu item to open the help file when right clicking the module/plugin.
When a user presses F1 search all the help files and not just one.
Also, you didn't mention it but I find this to be equally important, use the help file for intellisense too.