nested CHMs not searchable

[WebbJ]

Context: Flare versions 2.5 & 4
__________________________

We are finding that CHM files nested at the 3rd level are not returning results from a local Search.

I've not investigated this in detail yet, but is there a known problem?

The nearest situation I could find was a query in the Webhelp forum about using nested Help across a network.

Thanks in advance,

Seer

[Pete Lees]

Hi, Seer,

Yes, this is a known limitation of the HTML Help format. The index and search functions don't work recursively across more than one level of help file (but the TOC function does). See "Summing Up" in this page:

http://helpware.net/htmlhelp/how_to_merge.htm

So, suppose that you merge sub-slave file A into slave file B, and slave file B into master file C. The topics in A will only appear in C's search results if you add A to the Merge Files list in C.

Pete

[Richard Ferrell]

Pete is correct, Thanks! you want to keep your Slave CHM's at the same level

[AndrewW]

It's a shame that Flare doesn't enable you to specify additional merge files in the way that HTML Help Workshop does. The ability to merge at multiple levels is one of the best features of HTML help, especially if you work with large help sets over a long period of time.

[WebbJ]

Thank you each for your replies. May we start again, please?
AFAICT:
a. Flare (whether v2.5 or v4) does not support Search on CHM Help files nested to more than 2 levels.
b. The solution lies in adding those files manually to a [MERGED FILES] section of a CHM.
c. That is possible by use of HelpWare FAR or MS's HTML Help Workshop (HHW).

I have FAR v4.3 and HHW v1.31 and can open and edit the topmost CHM's HHC file.
However I cannot see any sections in it ([WINDOWS], [OPTIONS] etc.)
so I must have misunderstood something basic...

Regards, Seer

[Pete Lees]

Hi, seer,

Flare (whether v2.5 or v4) does not support Search on CHM Help files nested to more than 2 levels.

Yes, but strictly speaking it's the HTML Help format itself that doesn't support this facility.

I have FAR v4.3 and HHW v1.31 and can open and edit the topmost CHM's HHC file.
However I cannot see any sections in it ([WINDOWS], [OPTIONS] etc.)
so I must have misunderstood something basic...

In this case, you're editing the HTML Help project (.hhp) file for the master CHM. See these pages for instructions on how to do so with HTML Help Workshop:

http://msdn.microsoft.com/en-us/library ... S.85).aspx
http://helpware.net/htmlhelp/how_to_merge.htm ("Step 2 - The [MERGE FILES] statement")

Pete

[WebbJ]

Thank you for all contributions so far! I should have been referring to the Project (HHP) file. Now I am trying to understand exactly how to apply that advice.

This is not just about nesting CHMs - that works fine - but about nesting again to a 3rd level with Full Search at all levels:
Master-CHM . Sub-CHM . Sub-Sub-CHM.

Am I right to conclude that...:

"The solution is to create a HHP file for the master project, whose [MERGE FILES] section identifies every CHM file at all levels.
Put that in a decompiled copy of the Master CHM, then re-compile that through FAR/HTML Help Workshop.
The CHM files must all be delivered together so that the HTML Help Viewer can enable Full Search across all of their contents."

It would be good to post a 'clean' solution here for future reference.
(BTW: is this a manual process because it is rare, yet was usual for RoboHelp users?)

Also thanks for your patience.

Seer

[Pete Lees]

Hi,

Am I right to conclude that...:

"The solution is to create a HHP file for the master project, whose [MERGE FILES] section identifies every CHM file at all levels.
Put that in a decompiled copy of the Master CHM, then re-compile that through FAR/HTML Help Workshop.
The CHM files must all be delivered together so that the HTML Help Viewer can enable Full Search across all of their contents."

Yes, that all sounds correct. To be picky about the last point ("CHM files must all be delivered together"), CHM files in different folders can be merged provided that they are in the "help search path". The most common way to ensure this is to register the location of each help file under the registry key HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\HTML Help.

See Rob Chandler's Deploying HTML Help 1.x for more information on the help search path.

is this a manual process because it is rare, yet was usual for RoboHelp users?

Just speculation on my part: in tools like HTML Help Workshop, merging CHMs is a two-step process (merging the TOCs, and merging the indexes/searches). However, I believe that Flare may try to simplify the process by combining the two steps into one. This is usually fine except in the circumstance where you want to perform one step but not the other, as in your case.

If I'm wrong about this, I hope that one of the Flare experts here will correct me!

Pete

[WebbJ]

Thanks, Pete Lees. [I have stripped down this post, to focus on the solution]

I confess that when I evaluated Flare in May 2006 I did not spot that FTS was missing for recursively nested CHMs.
. . .
We are issuing the nested set of CHM files to publishing teams in English, to be translated into other languages before publication.
So the file structure & naming have to stay the same. Also these are not developers so the only toolset currently being used is Flare (with FAR as an option for any fixed, simple procedure).
. . .
There is no access to the end installation; the teams are just making up the DVD from which each version will be installed automatically. (i.e. no tweaking on the user sites!)
. . .
Is it just the master CHM that has to be decompiled, given a project (HHP) file listing all CHMs to be merged at the Sub-CHm & Sub-Sub-CHM levels, then re-compiled? Or would one need a set of HHP files, one for each CHM? If so, apart from the CHM's filename could they all list all CHMs?
. . .
Seer

[Pete Lees]

Hi, John (seer),

when I evaluated Flare in May 2006 I did not spot that FTS was missing for recursively nested CHMs.

I think the thing is that no tool supports FTS across recursively nested CHMs, because the HTML Help format itself does not support this facility. So, although you can recursively nest the TOCs, you can't do the same with the indexes and FTS data. In tools like HTML Help Workshop (and presumably also RoboHelp), where merging TOCs and merging indexes/FTS are two separate exercises, you can sort of work around this: nest the TOCs recursively, but merge the indexes and FTS data of all the slaves and sub-slaves into the master. As I understand it, this isn't possible in the Flare UI because the action of merging one TOC into another also merges the index and FTS data. Therefore, you'd need to configure the project settings for the master CHM outside Flare if you wanted to achieve similar results in a Flare-generated help collection.

Is it just the master CHM that has to be decompiled, given a project (HHP) file listing all CHMs to be merged at the Sub-CHm & Sub-Sub-CHM levels, then re-compiled?]

Yes, that's right. You'd merge the TOCs as normal in Flare (sub-slave TOCs into slave TOCs, and slave TOCs into the master TOC), and then just tweak the master project (.hhp) file outside Flare to add the names of every slave and sub-slave to its [Merge Files] section. Then recompile the master using HTML Help Workshop.

Pete

[WebbJ]

Pete Lees,

It worked!
The problem was just info. overload - I had too much info about nesting (not a problem) and recursion was in there somewhere.
Anyway I started afresh and applied the relevant instructions.

----------

In a nutshell:
(for the simplest case, starting from the Master CHM file from Flare with all 2-level nesting of TOCs & Indexes already set up)

Once per version of the product:
Use FAR's HH Project Editor to make a Project (HHP) file. Leave everything as is but the [Merge Files] section. Add all of the Sub-CHMs & Sub-Sub-CHMs to its list.

Once per language/version:
Use FAR to decompile the Master CHM into a folder. Edit the HHP file's [Merge Files] section if the CHM names are different (by language code). Copy the edited HHP file into the folder. Recompile via FAR. Issue all of the CHMs together.
----------
That's it! The 3rd level topics (in the Sub-Sub-CHMs) will be listed in Full Text Searches of the Master CHM.
Thanks to each of you... comments & corrections welcome.

Seer

[Pete Lees]

Hi, John,

I'm glad that you got it sorted.

Just a small word of caution about decompiling .chm files: this isn't a "round-trip" process, as some features that were compiled into the original files are not recoverable when you decompile. For example, I think you'll lose context help mappings and embedded index keywords. A better approach may be simply to work exclusively with Flare for as long as you can and then, at the very end of the project, use your preferred tool to edit the master .hhp file that Flare has added to the output folder. Then recompile with HTML Help Workshop.

More fundamentally, life would be easier if you could just eliminate the third level of nesting altogether. But I do understand that you may have good reasons for wanting to preserve this.

Pete

[WebbJ]

Pete,

Thanks for that note of caution. Fortunately we're not using either of those irreversible features at the moment.
However, that might well affect anyone who reads this and thinks they can achieve 3-level Search safely.

Also as you advise we will apply a once-off fix to each Help-version set as the last step before publication.

BTW you mention "the master .hhp file that Flare has added to the output folder". Did you mean the Project folder?
It seems not to be stored in the CHM file (e.g. as _Temp.hhp), so its settings must be somewhere else in the CHM...

We're writing detailed instructions so that our publishing team can decide what to do.
(whether to fix up a HHP file each time, ask us to do it by return or just ask us always to flatten level 3 into level 2 (Sub-CHMs).

I wonder whether MadCap or Helpware could turn that into a small utility to fix the Master CHM in the simplest case
(default settings + local Sub-CHMs & Sub-Sub-CHMs).

Seer

[WebbJ]

We've written the instructions and gained confidence in the method. Next, our publishing colleagues will review that, perhaps try it out for the French Help set and decide whether to adopt it as our standard procedure for enabling 3-level Help across all language variants.

We've noted these anomalies:

• The compilation generates many warnings, though none seem to effect the end result.
  The small bitmaps used to indicate an open pop-up window have to be declared in the HHP file's [Files] section and placed in the folder for compilation.

An offer, by way of thanks but also for feedback:

If anyone wants to try this out, or better still to draft a Knowledge Base article, we can forward the details (a doc. of the method + a sample modified HHP file).
In any case, if you do try this at any time - subject to the warnings about irreversible features in the previous post - please let us know how you get on.

Seer

P.S. Our publishing team have apparently done this without FAR, by feeding a HHP file (listing all the CHMs) with the ex-Flare project into HTML Help Workshop for compilation.