Searching in Run-time Master

[cindynotbrady]

I have a unique problem. We have a Master help file compiled of many separate hmxz files, but we also have individual screen help for each of our screens. In other words, when a user presses <F1> on a screen, it brings up the help for just that screen (hmxz file). I've trained each hmxz file to use the TOC of the master help. But now my problem is if they click the Search tab to perform a search, it only searches on the one hmxz file and not through the whole master. (I use runtime merging.)

I could have sworn I tested this before I decided to do this to make sure the Search tab actually searched through all the help, but it apparently isn't working. I will note that I recently changed the Search Platform from JavaScript to ASP, but I changed it back to see if that was the problem, and it wasn't.

Could I need to reapply my skin again to each of the help items before building the master help? Or was this never a possibility and I fooled myself into thinking it was.

[Tim Green]

Hi Cindy,

In other words, when a user presses <F1> on a screen, it brings up the help for just that screen (hmxz file).

Your users will only have access to an .hmxz file if they are editing the project in Help & Manual, so that isn't what they are viewing. You say you are using runtime merging, so it must actually be CHM/HTML Help.

The key question here is, do the TOCs of all the child files display merged into the TOC of the master when the users open the master CHM file? If they don't, then runtime merging is not working, and that would also be the reason you are not seeing the search results for all the CHMs in the runtime folder. The most common cause for this would be if the names of the project files and the CHM files created from them do not match exactly. Help & Manual can only store the project name + .chm in the master as a reference, because the child files are generated separately. If the child project is called child0.hmxz and the actual CHM is called introduction.chm, the master will look for child0.chm and will fail to find it. There won't be an error message, because in runtime merging this is not an error -- files that are not there are simply not included.

If this is the case you need to do the following:

1. Remove the current child projects from your master.
2. Change the names of the child projects to match the names of the output files.
3. Reinsert the re-named child projects in the master
4. Re-publish all the projects, including all the child projects

Naming the child projects:

It's important that the names should conform to CHM requirements:

• No spaces or non-alphanumeric characters in the names.
• Do not start the name with a number.
• For maximum compatibility, use only a..z, A..Z, 0..9 and the _ underscore character.

As an added improvement, you can also configure the child projects to automatically open the master TOC when the child is opened on its own. To do this, open the child project in Help & Manual and go to Configuration > Publishing Options > HTML Help > Extended .HHP Settings. At the lower right is a setting "Which table of contents should the child displayed when opened directly?" Set that to the project name of the master project (which must also exactly match the name of the master CHM file, of course).

[cindynotbrady]

All those steps you mentioned are indeed how I am doing things. I think the problem comes with the way our programmers tie the help to each screen. Each screen has a separate chm, which is tied to a dll of each screen. So when users press <F1>, only help for that screen shows up. On our end, we must name the chm with the matching name that the programmer named it. I'm sure you understand how that works.

However, when users press <F1>, only help tied to that screen shows up. However, just like you explained above, I trained that individual help file to use the Master help table of contents. So the Search tab, I would have thought, would search through the entire help. But I think in reality, it is only searching that one chm help file. (I'm sorry I called it an hmxz. I know how the two are related, but when I build my master, I insert an hmxz for runtime, knowing that the chm must match the hmxz perfectly.)

So to explain further with pictures, I as the technical writer, use a Help Tracing tool designed by the programmers to find out what the chm should be called for the screen, and any keywords that can link directly to field help, like so:

helptracing.png

I create the help naming it with the matching chm name given me by the programmers. Then I change the Table of Contents, so that this particular help uses the Master Help TOC, rather than its own. And then I include that chm in the Master Help.

So when users press <F1>, they get the help for that particular field or screen, but it is in connection with the all-inclusive TOC, as shown below. (See how in the following example that the Payments Due field group has "no topics above this level," is showing its own header on the help, but you can see where it fits in the master TOC.)

paymentsduefieldgroup.png

When users click the <Search> tab, the search is really only looking in that one help file. I was hoping it would search all the help in the Master Help. Here's what my Master Help TOC file looks like in H&M:

masterhelp.png

I'm hoping it's user error, and perhaps I need to try reinserting each of the help files into my master help again (time consuming, but I'm willing to do it). I just need to know that in theory, searching will work from the <F1> key tied to a specific help screen, but using a TOC master help.

[cindynotbrady]

For further explanation, if I press <F1> from the screen I used in the example above and search for the word "rebate," the search finds no matching results, as shown below.

nofind.png

I know that on another screen, I do in fact have a field called Int Rebate Method, and that screen has been included in the Master Help TOC.

So I go to the screen with the Int Rebate Method field, and I press <F1> from that screen and do a search on the word "rebate." This time the search finds it, but as you can see, it only finds instances of it on this particular screen (the Precomputed Loans screen).

precompute.png

It would be cool if I could also train the search to point to the complete master table of contents.

[Tim Green]

Hi Cindy,

Thanks for the detailed report! I'm not 100% sure on this myself. I'm asking Alexander to provide feedback on it, because he is the expert on everything to do with interfacing with CHM files. It's possible that search may not be available throughout the entire system if the call is made to the child CHM. I'm going to have to check with Alex to make sure on this, however.

[cindynotbrady]

You're a peach! Thanks!

[cindynotbrady]

I haven't heard back about this issue, so while you are all still researching it, I was wondering whether or not you could maybe also look into a Search field that could be displayed in the skin of a chm. And the search could find results from all chm files in the same folder.

Maybe something like this:

searchboxes.png

[Tim Green]

Hi Cindy,

CHMs don't have skins -- the only thing you can skin in a CHM is the actual topic page itself. The viewer is a Microsoft/Windows component that cannot be configured in any meaningful way. You definitely can't add things like search widgets. All the configuration options it supports are available in Configuration > Common Properties > Help Windows > HTML Help Options.

On the search issue: The search will be global and will include the master file if the modular project is structured correctly. If all the files are created by Help & Manual the internal structure will be correct automatically, provided that the following rules are observed:

1. The names of CHM files must exactly match the names of the projects that created them. Otherwise their contents won't be found. This means that your projects should also have CHM-compatible names (no spaces, no special characters, no non-alphanumeric characters). It's best to use only a..z, A..Z, 0..9 and the _ underscore character.
2. All the component CHMs must be created by Help & Manual.

If these two conditions are satisfied, then a search in the entire help when opened via a child module will find all occurrences of the search term in both that child module and the master (since the master was opened by the child). However, it won't find the term in the other children, because by default the child only knows about its relationship with the master.

If you want the search to also find search terms in the other children, you need to tell each child that all the other children exist:

1. Open the child module in Help & Manual and go to Configuration > Publishing Options > HTML Help > Extended .HHP Options.
2. In the editing box on the left, add a [MERGE FILES] as the header and then a list of all the other child CHMs, with one file name on each line, like this, leaving out the name of both the current child and the master, of course (again, no spaces or special characters in the names):

   Code: Select all

   [MERGE FILES]
   child_a.chm
   child_b.chm
   child_q.chm

3. Then recompile all the children and the master. That's it.

[cindynotbrady]

Totally worked! Thanks so much!

[cindynotbrady]

Just to be sure, is there any harm if I include the Master file and/or the current child? I will have to do a LOT of copying and pasting, and it would be easier not to have to slow down and find the current help file name as I paste this huge lists of chm's into each of the individual hmxz files.

[Tim Green]

Hi Cindy,

It's better to not include them but it won't break if you do.

[cindynotbrady]

Oh, that's good. I'm realizing this work around is not my favorite. You know I love this product more than anything ever, but I don't love that I have to enter every chm to include in the search. That means if ever our developers create new screens, which is often, we'll have to copy and paste that chm into every help file. We have more than 200 separate chms.

I know your great minds will think of a fix for this eventually. Let me know when you do. I eagerly await the next version release.

[cindynotbrady]

I found another problem when creating our help this way. We're five years down the road of creating our help, so it may be too hard to teach our programmers a different way. However, this is how things work currently.

Our programmers create a chm name for each of our screens. In each of those screens, they create a Keyword as well. We create a chm matching that name and enter keywords in the Keyword field. Then our end users can press <F1> and see the help for each particular field.

When I apply the fix mentioned above, the <F1> key now brings up every instance of that keyword.

For example, the Account Number field is displayed on many of our screens. But because it's part of its own CHM, the programmer can call the field "AccountNumber" and it's fine.

This worked fine before when every chm was its own chm. But now that I'm including Merge Files, when I press <F1> a box is displayed asking me which Account Number I want displayed, as shown here:

topicfound.png

Therefore, at this point, I really need to go back to my programmers and either have them create more unique keywords for each field for each chm, or in my opinion, we have screen help from the <F1> key that leads to field help. I thought I would document my results in case any others run into this similar problem.

[Tim Green]

Hi Cindy,

Well, unfortunately you're getting exactly what you're asking for... Once you create a merged help in which search and references work throughout the entire help system as though it were a single help file, then search and references will work throughout the entire help system as though it were a single help file. So if the same keyword is used multiple times, all instances of it will be found. Once you have gone down that path you can't then try to restrict the search to just one CHM module -- it has already been opened up to all modules. The only way around that would be for the programmers to make the keywords unique per module, for example by adding a module prefix to each one.

[cindynotbrady]

So I think I'm close to convincing the programmers to get rid of field-specific help from the F1 key, and instead when our users press F1, the help for the screen appears, and on each screen, links to each individual help will be there (thereby essentially getting rid of the keyword problem we're having). However, to implement this change you suggested with the Merge Files, I still have the issue of having to add to all 300+ files, so that the search can be across all the chms, not to mention new screens which will be added in the future, which means updating all the 300+ Merge Files again. Is there some sort of javascript or work around so that maybe I only have to update one help file, and the rest will follow suit? Does that make sense?