Context calls to 2nd level nested chm-library doesn't work

[Baum&Help]

Hi,

We add software and associated .chm-help files to existing applications of customers. These applications come all with a standard master that include a lot of child .chm-files.
We compiled our own master help file that includes our own help files as well as the standard children using runtime merge. We created .ali and .h files with aliases and id's for the standard modules as well as for our own and add them to the complilation.
This works fine. Except for calls to topics in .chm-files at the 2nd level.
For example 3001 to a topic in sweditobjects.chm: realworld.chm > swobject.chm > sweditobjects.chm

All calls using the api-test of HTML Workshop with this id that belongs to a topic in sweditobjects.chm fail. We tried the folllowing .ali adresses. If I am correctly informed, the first address should work.

ObjectsAndAttributes=master::/swobject.chm::/topics/ObjectsAndAttributes.htm
ObjectsAndAttributes=master::/swobject.chm::/ sweditobjects.chm::/topics/ObjectsAndAttributes.htm

I could find an answer to this question. Maybe someone can help me.

André van den Boogert,
Realworld Systems

[Tim Green]

Hi André,

The HTML Help system is very ancient, it hasn't really been updated at all since Windows 98, and it is unable to route help calls through the master to the child. You need to make your calls to the child directly and configure your help system so that the entire merged TOC gets pulled up automatically when you do this. In Help & Manual you do this (in the child) in Project Explorer > Configuration > Publishing Options > HTML Help > Extended .HHP Settings. There you can specify the master file to be opened automatically when the child is accessed directly.

[Baum&Help]

Thanks for the answer, although you might not be suprised that I was not happy with it.
I did some more testing to get to the bottom of this. This is why my answer is delayed.
In contradiction to your statement I was able to facilitate calls through a master to a child by suppying .ali and .h files to the compiler. But the topics in the 2nd level children still couldn't be adressed. I found a kind of workaround for this problem by adding the 2nd level libraries in a special topic at the end of the TOC.
When a call is made to a topic id in the 2nd level child, it looks like that the first reference is found and used and the TOC of the 1st level child is unfolded, which is exaclty what I want, because it is the default behavour in the help system that comes standard with the application.
But strangely enough this does not work for the libraries we create ourselves, which are 1st level children. The TOC isn't unfolded. For those libraries I used the mechanism you mentioned. The disadvantage is that these libraries cannot be used without the master, because this is by name hardcoded, but for this I take my loss.
But by supplying an .ali and .h file of our own modules, calls through the parent to topics in our own libraries succeed.
For now I am satisfied. Thanks for the help.

[Alexander Halser]

Hello André,

I assume that you include additional map files into your master CHM, don't you? Help & Manual supports that by letting you modify the content that goes into the .HHP file. This option is in Project Explorer > Configuration > Publishing Options > HTML Help > Extended HHP Settings.

You basically need to include either an alias file or a context number map file, or both. "ObjectsAndAttributes" seems to be an alias in your case. Is that correct? So all that is needed is an external address to the CHM file that the topic actually contains. In your case, you have compiled a file "swobject.chm" and this CHM contains a topic "ObjectsAndAttributes.htm".

Now you want to make a call to the master help file by, say a context number, that is mapped to the alias name, which then points to the external help file. As a result, that external topic should be displayed in the master help file as if it was internal. Presumed that the external file is there.

This should work this way. However, there are a few things that puzzle me.

First, is the external file "swobject.chm" compiled with H&M or is that a 3rd party file? The question I ask is that you are referencing a topic in an internal "/topics" folder of that CHM. If the CHM indeed has this structure, the reference is probably ok, but if it was compiled with H&M, remove the "/topics" part, because H&M stores all topics in the root of the CHM.

The second thing that strikes me, is the prefix "master::/". Is that literal or just a symbol? This part denotes the protocoll for the HTML browser (which is MSIE in HTML Help) and "master::/" is not a protocol that I have ever heard of.

Neither do I know of a way to route context help calls through 2 levels of CHMs.

So, instead of

Code: Select all

ObjectsAndAttributes=master::/swobject.chm::/ sweditobjects.chm::/topics/ObjectsAndAttributes.htm

try do address the target directly

Code: Select all

ObjectsAndAttributes=ms-its://sweditobjects.chm::/ObjectsAndAttributes.htm

A CHM file is a container similar to a ZIP archive, with an internal file/folder structure. With "ms-its://" you tell the browser (in case of HTML Help, that is MSIE) that you are going to open a CHM file. It doesn't do any harm to explicitely include the protocol, although it might not be necessary. With "sweditobjects.chm::/" you address the root folder of this CHM file. The root folder must contain a file called "ObjectsAndAttributes.htm" to make this call work.

[Baum&Help]

Thanks for your response.

The third party help libraries we want to add are most likely not created by Help&Manual, esp. because instructions for customizations by the supplier of the help (a subsidiary of Ge) are written for HTML Help Workshop, which of course is no option.

I indeed used the facility of H&M to enter extended HHP Settings to pass .h and .ali files for all modules. What I actually did is:

1) provide all addresses in the .ali files in the form of e.g. master::/sweditobjects.chm::/topics/ObjectEditors.htm where ‘master’ is the name of the master chm-file without the suffix, which appeared not to be necessary. (I also tried with - and without - the folder ‘topics’.) And
2) add the 2nd level libraries to the TOC of the master (in a special ‘technical’ topic with an appropriate ’construction icon’.)

Without explicitly adding these 2nd level libraries it is impossible to open these libraries in the TOC of the master.

In the past I already tried several formats of the topic addresses, including the ones with the ms-its: protocol, but after trying this again I found out that the result is that a page error is raised: “This program cannot display the webpage”, and that the child library is opened with its own TOC, which bye the way can be explored.
So this leaves me with a solution that cannot be understood completely and isn’t elegant, but works. A little confusing.

In the end I wonder if it is possible to let H&M extract the help context numbers of runtime merged children and provide these to the master.

[Alexander Halser]

In the end I wonder if it is possible to let H&M extract the help context numbers of runtime merged children and provide these to the master.

Not automatically. But those files don't change often, do they? You could import that CHM to a temporary project and extract the context numbers.

[Baum&Help]

Yes, that is right.
But regardless that, do you think there is a better way of achieving my goal?