Doc for plug-ins

[themint100]

Hi all,

This is more of a "design/structural" than a "what button do I press" question.

I have a rather large application that has a "base" .chm file associated with it (already quite huge). Our customers may also purchase plug-ins, but won't necessarily all have the same set. So while one user's application may look like this:

Main-app
+plug-in A
+plug-in B

another's may look like this:

Main-app
+plug-in A
+plug-in E

I distribute a .chm file with the main-app.

In the table of contents for my main app's .chm file, I'd like to have a section called "Plug-Ins" that could be dynamically populated. I'd like to achieve that by distributing a small set of help with each plug-in that could be 'dropped' into a help directory and extend the help system after restarting.

Since we're dealing with compiled help systems, I think I already know the answer. I don't think this is possible right now, but has anyone had a similar problem/solution? Any options for dynamic loading at runtime?

Alternately:

1) If I have to do separate .chm files for the main-app and each plug-in, can I at least force them to open in the same help window?

2) If I have separate .chm files, I'd like to have cross-references from the plug-in projects to the main-app project. Are cross project references possible without entangling the two component projects? (I'd be fine if the links in the plug-in help didn't work if used without the Main-app help in place.)

Thanks in advance,

-Greg

[Guest]

Alas. You can do all of these things - but not dynamically.

RoboHelp's "merged help" function uses the TOC to specify the plug-in modules for each customer. That TOC is compiled into the .chm and can't be affected at run time. So you could easily create a custom .chm for each client with the appropriate plug-ins, but if the client buys a plug-in later, you can't drop an extra .chm on their desktop and have the TOC find it.

Now, about cross-referencing separate .chms - Robo-speak for this is "linking to external help topics." That has some possibilities - but again, it would be hard to link from the master .chm to a module that may or may not be there.

It's no trouble at all to link from the modules to the master, since you know the master will be there. And I believe that you choose whether the linked topic comes up in the same Help window. But you aren't going to get the whole TOC unless you merge before compiling.

This doesn't mean you can't get what you want - just that you will have to be sneaky about it. I'm trying very hard right now to remember which of the gurus is the expert on merged and otherwise linked .chms - MergeThis (Leon), is it you, or are you a WebHelp merger?

Greg, you should probably try a couple of experiments with external topic links. You may find a clever workaround that nobody else has - and if you do, please tell the world!

Elisa

[themint100]

Thanks, Elisa.

Yeah, the dynamic thing is my main issue, unfortunately.

Another idea...is there any way to modify the help viewer itself when it's started? What if I tried adding a menu item to the menu bar that showed different help systems. If that were possible, then it might be simple enough to populate that dynamically.

Any idea where I'd check to see if the viewer were modifiable?

-Greg

[Guest]

Hi Greg,

Actually, one of the things Elisa said isn't quite true - you CAN affect the TOC of a compiled .chm file dynamically simply by not making one or more of the slave projects available. If you build a merged project with slave projects A, B and C, you will see projects A, B and C in the TOC of the merged help. However, if you remove the project B chm file from the directory containing the .chm files, the TOC of the compiled, merged project simply omits the missing project.

Admittedly I've only tried this with a single slave project, but the principle should apply to a merged project with several slave projects. So if you build your merged project with ALL the plug-ins, but only deliver the relevant .chms to the relevant users, the TOC should adjust accordingly.

Hope this helps,

Anne

[Guest]

Greg,

Just tried a merged project with two sub-projects. If I rename or remove either of the sub-project .chm files, they no longer appear in the TOC.

Anne

[Guest]

Anne,

I'm an idiot. Of course it would work by elimination - just not by addition.

What happens when you put a sub-project .chm back into the folder?

Elisa

[Guest]

Hi Elisa,

As long as the merged project is compiled with all the potential sub-projects present, the sub-projects will appear in the TOC as soon as the relevant .chm is added to the directory containing the master .chm. The index and search also adjust to reflect the sub-project .chms that are actually available.

Regards,

Anne

[themint100]

Hi all,

Thanks for the replies. Lots of hoops...

So here's what I gather I need to do:

1) Create the main project and specify 'stubs' for any subprojects that I may want to distribute later. So my logical tree might look like this:

Main Project
- plug-in A
- plug-in B
- plug-in C
- plug-in D
.
.
.


(let's say I specify 15 or 20 stubs to give myself plenty of room).

2) When a plug-in is written and I want to distribute help for it, I need only distribute it as the "plug-in A" .chm and it will automagically appear in the TOC for the Main Project (since 'plug-in A' had been specified as a subproject).

The only other thing I think I need to do is recompile the Main Project whenever I finish a plug-in, in order to get the updated Map IDs (to enable F1 help). I'd have to distribute that every time someone bought a plug-in. The Map IDs would include index entries for *all* plug-ins, but that would be OK. When you have subprojects, do you still get one main Map ID file if you recompile the main with all the subprojects?

Thanks in advance,

-Greg

[themint100]

Dang.

Went through and tried the proposed idea, and it *almost* works. Thanks so far!

Few last little problems:

1) When you merge in a subproject, the Map ID files aren't merged into the main project (although as I write this, I suppose I could do this by hand, assuming I keep the namespace for Map IDs of each subproject from colliding with the main project). I don't see any way around this, but I guess that's a minor task.

2) When I merge the subprojects, I have some TOC weirdness. The TOC in my main project looks like this:

<Book>Chapter 1
<Page>Topic 1
<Page>Topic 2
<Book>Plug-Ins
<Proj> SubprojectA.chm::/SubprojectA.hhc
<Proj> SubprojectB.chm::/SubprojectB.hhc

With no plug-in .chms loaded, I'd still like a user to see the Book, so they know to expect them. But when I generate, the TOC ends up like this:

<Book>Chapter 1
<Page>Topic 1
<Page>Topic 2
<Book>Plug-Ins
<Book>Subproject A
<Page> SubprojectB

The first merged project is added as a book, while the second is added as a page under that. In this scenario, Subproject B should come in as a book, but it's getting forced down one level in the hierarchy. FYI, I have a top-level book in the TOC of both subprojects.

3) What is an .hhc file?

-Greg

[Guest]

Hi, Greg. Sounds like you are having real success.

1) Not sure why this happens - can a map ID person help out?

2) This is a bug related to the HTMLHelpViewer. See this post for more information. The course of least resistance is to leave the plug-in books at the top level. Since it doesn't seem like you need to integrate them into disparate places in the TOC, will the top level work? (There is a fix, but it requires HTMLHelp Workshop or FAR - some external help editing tool.)

3) The <projectA.hhc> items in your master TOC are references to the plug-in .chms' TOCs. An .hhc file is a table of contents for a help project. You can open it in Notepad - it's just a text file - and see what it looks like.

Keep going - the light at the end of the tunnel might not be an oncoming train!

Elisa

[themint100]

Thanks Anne & Elisa,

Sorry for the extended thread, just trying to get my final process down...another question on merged projects.

Given that I have a main app and some plug-ins, I figured I'd limit the cross-references to exist only in the direction from the plug-in help projects to the main help project. However, when I'm editing one of the plug-in projects and try to do an external topic link I find that:

a) I have to link to an already compiled project file (.chm), and not to the source files as I might expect. If I recompile the main project can my external topic links (from the plug-in projects) potentially break?

b) Robohelp wants to copy the main-app.chm file into the plug-in help project. I read in the help that: "You must keep the external .CHM file in the same folder as your project .CHM file in order for the link to work properly." While I may want to put all the .chm files in the same directory at distribution time, won't specifying the same output directory for both the main-app and all the plug-ins cause auto-generated files to be trounced over left and right?

-Greg

[Guest]

More great questions.

a) No, recompiling the master .chm won't wreck your links to the master from the slaves, as long as you didn't change the topic filenames or bookmarks you are linking to. In fact, recompiling the master won't touch the slaves at all.

b) No, you won't trounce anything because there's only one output file per project (master or slave), and they all have different names. Output files aren't the problem.

I understand the confusion about the "copy to project folder" links - it sounds recursive in the extreme, doesn't it? I've read the help about 42 times, and of course it isn't specific about creating links between slave and master projects. I think you are just going to have to test this with your set of small test projects. Run the whole cycle - create main, compile main, create subs, create topic links, compile subs, shove everything into an output folder, and test. Then change the main and recompile, change a sub and recompile, move subs in and out.

My hunch is that all this copying of .chms into each other's project files is just to form the links that will actually work in the Big Output Folder where all the finished .chms will live. I don't think the external .chms actually get packed into the project .chm, just the references. It's just a hunch, mind you, so don't quote me on this.

Hope this is at least a direction to go in,
Elisa

[themint100]

Thanks again, Elisa & Anne.

Wanted to give you an update.

I think you're right, copying the target .chm to the current project is just for setting up the cross references. However, if I have lots of subprojects, this will make for a nightmare on Windows, given that I have to copy a 25 or 30 Mb file into each subproject just to do cross-reference. (If I could set up a unix type link on a windows box, that problem would go away, but alas...)

So I've arrived at the following choices:

1) Stick with a .chm for the main project, create stubs for each plug-in project, but don't do any cross referencing between projects. <<sigh>> This lets me have a single TOC, and I can distribute doc for each plug-in separately, so it looks like one system. I'd then always regenerate the master project to get an updated .h file.

-or-

2) Looking at a merged Webhelp project. I've been posting over in that forum, and have already tried the process using some ideas on Peter Grainge's site. The advantages are that you can do true cross project references, distribute new projects without having to create stubs in the "main" project, plus you get true cross platform compatibility. I'm sorting out how to merge .h files and use them to call help sections in webhelp, but if that works, I may have to tease things apart and go that route.

So while not a 100% success, I've at least found the boundaries, and I can decide what to do.

Thanks very much for all your help!

-Greg