19 Replies Latest reply on Dec 15, 2011 7:34 AM by Peter Grainge

    Merged help projects and context sensitiviy

    Hippopodius
      I am using RoboHelp x5 and have created a master project and I have 3 .chm files merging into the master project. I've gotten TOC, Indexing, and Searchable help to work. But what about context sensitivity?\

      Thanks!
        • 1. Re: Merged help projects and context sensitiviy
          Pete Lees Level 2
          Hi, msmanitoba, and welcome,

          There are two ways to handle this.

          1) Pass the context calls directly to the slave help files, bypassing the master and using "Solution #3" in the following article to present the user with a unified help system.

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

          2) Channel all the context calls through the master help file, as described in the following article.

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

          Both are rather kludgy workarounds, but they work well when all the project settings are correctly specified.

          Pete
          • 2. Re: Merged help projects and context sensitiviy
            Hippopodius Level 1
            Thanks, Pete.

            Not clear about the solution though.
            It says:
            ***************************************
            Solution #3:
            You could configure each slave CHM to use the Master TOC and merge with all other CHMs (We showed this in Step 3 of the Demo Project above). Thus each Slave when opened directly will have the same content as the Master. ...
            **************************************
            How would using the Master TOC affect context sensitivity?

            Per your comment 2):
            I did try creating a redirect file. That's not working either. But I feel that maybe some steps in the process aren't clearly specified. For example, can I eliminate "its:" protocol? I don't want the help to open in IE ... I want it to open in Windows help.

            And can you explain this in more detail:
            "What the Helpware site doesn't explain is that the ALIAS section of the .hhp file must contain at least one bookmark-free reference to the redirect.htm file; if every redirect line in the section has a bookmark appended to it then the context help call will fail. So to fix the problem, I added the following two lines to your .hhp file:

            [ALIAS]
            Dummy_Unused=redirect.htm
            ...

            [MAP]
            #define Dummy_Unused 0
            *********************

            "bookmark-free reference" ... does that mean no references to bookmarks within the html file? I don't have any in my context sensitive mapping; therefore, I shouldn't have to use that Dummy_Unused line, correct?


            • 3. Re: Merged help projects and context sensitiviy
              Hippopodius Level 1
              Maybe I should also say what the requirements are for these help projects:
              -- a merged help project to provide context sensitivity, merged TOC, merged index, and full text search across all modules
              -- but, I also need those individual modules to be separate because the applications they are attached to can be used separately

              Thanks so much!!!
              • 4. Re: Merged help projects and context sensitiviy
                Pete Lees Level 2
                Hi, msmanitoba,

                > How would using the Master TOC affect context sensitivity?

                If you pass context help calls to a slave .chm file directly then users don't have the means to browse beyond the contents of that file to the other help files in the collection. The trick of Solution #3 is therefore to display the TOC of the master .chm file in each of the slaves so that users can get to topics in other help files if they wish. In effect, there shouldn't be any noticeable difference between the appearance of a slave .chm file and that of the master file.

                Whether or not you use this technique shouldn't have any effect on context sensitivity, though.

                > For example, can I eliminate "its:" protocol?

                Yes, you can do this, but use of this protocol will not cause the target topics to display in Internet Explorer if you've set everything up correctly.

                > What the Helpware site doesn't explain is that the ALIAS section of the
                > .hhp file must contain at least one bookmark-free reference to the
                > redirect.htm file

                I suspect that this is the reason why you're running into problems with this method. If you look at the sample .hhp file in the "Solution #1: Mappings on the Help Side" section of the Helpware article you'll see that every alias to the redirect file has a bookmark appended to it:

                IDH_SLAVE1_INDEX=redirect.xhtm #IDH_SLAVE1_INDEX
                IDH_SLAVE1_ANOTHER=redirect.xhtm #IDH_SLAVE1_ANOTHER
                IDH_SLAVE2_INDEX=redirect.xhtm #IDH_SLAVE2_INDEX
                IDH_SLAVE2_ANOTHER=redirect.xhtm #IDH_SLAVE2_ANOTHER

                In the test files I've created (and that I can send on to you if you want), the fact that there isn't an alias without a bookmark causes the method to fail. So you'd need to add an additional alias like this:

                Dummy_Unused=redirect.xhtm

                and map the topic ID to an unused context integer in the map (.h) file, like this:

                #define Dummy_Unused 0

                Pete
                • 5. Re: Merged help projects and context sensitiviy
                  Hippopodius Level 1
                  More questions ...
                  1. In my case, I don’t have bookmarks as part of the context sensitivity path. I want an entire html page to display. So, I don’t have to use the Dummy_Usage line, correct?

                  2. What should the master project’s .h file contain? Right now, I only have one entry to the one html file it contains. I created an “empty” master project.

                  3. I notice that RoboHelp wipes out or adds to the edits I make (via EditPlus or Notepad) to the .hhp file – why is that? I noticed this days ago so I always have a backup to replenish my edits in the real .hhp file. But it’s really annoying.

                  4. Will context sensitivity be easier with RoboHelp 7?

                  Thanks, msmanitoba
                  • 6. Re: Merged help projects and context sensitiviy
                    Pete Lees Level 2
                    Hi, again,

                    > 1. In my case, I don’t have bookmarks as part of the context sensitivity
                    > path. I want an entire html page to display. So, I don’t have to use the
                    > Dummy_Usage line, correct?

                    No, the Dummy_Unused entries were required to work around a limitation in the Helpware solution. Now that I test this again, though, the problems I encountered yesterday for which adding the Dummy_Unused entries was the solution don't seem to be recurring. So, probably best to forget about this for the time being.

                    > 2. What should the master project’s .h file contain?

                    It should contain all the context help mappings for all the help files — master and slaves. So, to the mappings for the master help files you would append the entries from the .h files for the slaves, like this:

                    // Master help mappings

                    #define IDH_MASTER_TEST1 1
                    #define IDH_MASTER_TEST2 2
                    #define IDH_MASTER_TEST3 3

                    // Slave #1 mappings

                    #define IDH_SLAVE1_INDEX 4
                    #define IDH_SLAVE1_ANOTHER 5
                    #define IDH_SLAVE2_INDEX 6

                    Likewise, the alias (.ali) file for the master project should contain the aliases for all the help files. But in this case you associate the topic IDs for the slave topics with the redirector file, to which you append the appropriate IDs again, like this:

                    ; Master help aliases

                    IDH_MASTER_TEST1=master1.htm
                    IDH_MASTER_TEST2=master2.htm
                    IDH_MASTER_TEST3=master3.htm

                    ; Slave #1 aliases

                    IDH_SLAVE1_INDEX=redirect.xhtm#IDH_SLAVE1_INDEX
                    IDH_SLAVE1_ANOTHER=redirect.xhtm#IDH_SLAVE1_ANOTHER
                    IDH_SLAVE2_INDEX=redirect.xhtm#IDH_SLAVE2_INDEX

                    Then, in the redirector file, you set up a series of mappings between these topic IDs and the corresponding topics in the slaves, like this:

                    if (Code == "IDH_SLAVE1_INDEX") URL="its:Slave.chm::/slave1.htm";
                    else if (Code == "IDH_SLAVE1_ANOTHER") URL="its:Slave.chm::/slave2.htm";
                    else if (Code == "IDH_SLAVE2_INDEX") URL="its:Slave.chm::/slave3.htm";

                    This probably sounds more complicated than it is in practice. Once you've got to grips with how the method works, it's actually quite straightforward.

                    > 3. I notice that RoboHelp wipes out or adds to the edits I make (via
                    > EditPlus or Notepad) to the .hhp file – why is that? I noticed this days
                    > ago so I always have a backup to replenish my edits in the real .hhp file.

                    I'll have to pass on that, as I'm not currently a RoboHelp user. Perhaps someone else following this thread can comment.

                    > 4. Will context sensitivity be easier with RoboHelp 7?

                    As far as this issue is concerned, I doubt it, because we're using an under-the-hood technique to work around limitations in the HTML Help format. Users of Flare, Doc-To-Help, and all other help authoring tools have to jump through the same hoops to get context sensitivity to work seamlessly in merged help projects.

                    Just to repeat what I said yesterday, I have a sample help collection illustrating this technique if you'd like me to send it to you off-list. Maybe that will make things a little clearer.

                    Pete
                    • 7. Re: Merged help projects and context sensitiviy
                      Hippopodius Level 1
                      By the way, Pete Lees rocks!!! He answered my questions and his sample help collection really helped me. Thanks, Pete!!
                      • 8. Re: Merged help projects and context sensitiviy
                        lovermont
                        Ms Manitoba, or anyone else,
                        Have you tried this method with RH7? We had this method working well with RHX5, but something in RH7 is breaking it.
                        (I noticed Pete doesn't use RH!?!?)
                        • 9. Re: Merged help projects and context sensitiviy
                          hermi14
                          Hello and happy New Year. Has anyone successfully implemented context sensitivity with merged projects in RH7? If so, which method did you use? Thanks.
                          • 10. Re: Merged help projects and context sensitiviy
                            Peter Grainge Adobe Community Professional (Moderator)
                            You don't say which help output you are generating.

                            • 11. Re: Merged help projects and context sensitiviy
                              hermi14 Level 1
                              Sorry: Webhelp is preferable but HTMLHelp would be acceptable.
                              • 12. Re: Merged help projects and context sensitiviy
                                Peter Grainge Adobe Community Professional (Moderator)
                                The two are not readily interchangeable. WebHelp is the format you should use if the help is to be server based and HTML help is the format for locally installed help.

                                For WebHelp we use the startpage'htm#path/targettopic.htm method and it works well. See my site for more information.

                                • 13. Re: Merged help projects and context sensitiviy
                                  hermi14 Level 1
                                  Thanks. Now that I understand the difference between Webhelp and HTML Help, I see that this topic only covers context sensitivity with merged *HTML Help* projects (which use the CHM file). What happened was that I searched for this topic across several forums and failed to notice that the topic covers "RoboHelp for HTML Help" (the output type) not "RoboHelp for HTML" (the user interface type)!

                                  I see now that my project must use the Webhelp format and I am happy to learn that context sensitivity for Webhelp merged projects has been successfully worked out and documented already as compatible with RH7!!!

                                  Due to a combination of VPN access issues, the fact that I have only one other writer working on my project, and my deep distrust of applications like RoboSource Control (which has been confirmed by just a little bit of testing), I've decided to use merged projects instead of source control as a collaboration tool.

                                  I'm sure you will hear more from me. You rock (rap, or otherwise harmonize)!!!
                                  • 14. Re: Merged help projects and context sensitiviy
                                    Peter Grainge Adobe Community Professional (Moderator)
                                    Check what you plan to do with your developers. This affects their calls to the help.

                                    • 15. Re: Merged help projects and context sensitiviy
                                      EileenPalsson Level 1

                                      Hi, I'm wondering if anyone has done this (merged help projects with context sensitivity) in RH8 (output: CHM) and whether there is any newer information. We have a master project with three slave CHMs, and we finally got those working together seamlessly, but without context sensitivity -- we're just getting started on that aspect. Any advice would be appreciated!

                                       

                                      BTW, the requirement that I've found mentioned on various threads that the master project not contain any topics does not seem to apply (or, not anymore). On the contrary -- if there are no topics and no index entries, the index doesn't work. Same with the requirement that the window be defined as a global window ($global_windowname). Our project works fine (so far) even though the master project contains topics and the windows in the projects differ.

                                      • 16. Re: Merged help projects and context sensitiviy
                                        Peter Grainge Adobe Community Professional (Moderator)

                                        I am just focussing on your second paragraph about the parent having no topics etc.

                                         

                                        First that is more for WebHelp and is because of the way cross project links are created. As with merged CHMs, you can have your source projects scattered all over the place and as long as you generate to one location, the merge will work. However, whilst you can do that with WebHelp it is not recommended. You would have a bit of a time creating cross project links as you would have to stop and work out the relative path in the output and manually enter that. By following the method on my site, you can use the interface to work out the relative path.

                                         

                                        For WebHelp, the parent does have to have a topic but it is a redirect so it is not seen.It's quite OK to have other topics in the parent as long as you avoid parent / child links. With merged CHMs you don't need the redirect because, to repeat, cross project links are not an issue there.

                                         

                                        Also in merged WebHelp, the parent index can be blank and the indexes in the child projects all display merged. I'm not sure that would be true in a merged CHM setup.

                                         

                                        Key point here is to keep in mind different rules apply for merged WebHelp and merged CHMs and you need to keep that in mind whenever you read any post.

                                         


                                        See www.grainge.org for RoboHelp and Authoring tips

                                         

                                        @petergrainge

                                        • 17. Re: Merged help projects and context sensitiviy
                                          msmanitoba

                                          Here I am back at it and wondering if there is an "automagic" way to merge the .chm files with RH9 ... has anybody explored this?

                                           

                                          Thanks in advance,

                                          msmanitoba

                                          • 18. Re: Merged help projects and context sensitiviy
                                            Peter Grainge Adobe Community Professional (Moderator)

                                            If you are using RoboHelp 9 maybe Item 13 in http://www.grainge.org/pages/authoring/rh9/using_rh9.htm will help.

                                             

                                            Adobe are aware of the problem.

                                             


                                            See www.grainge.org for RoboHelp and Authoring tips

                                             

                                            @petergrainge

                                            • 19. Re: Merged help projects and context sensitiviy
                                              Peter Grainge Adobe Community Professional (Moderator)

                                              RoboHelp 9 users should update to the just released Service Release 9.0.2.

                                               

                                              Click here for information

                                               


                                              See www.grainge.org for RoboHelp and Authoring tips

                                               

                                              @petergrainge