How you create links between modules depends to a great extent on whether you use runtime or publish time merging. If you use publish time merging all the modules are always present so you can use normal topic links. If you use runtime merging for CHM files (it is only supported in CHM) you should use the A-link method (see below) for all links to modules which might not be present at runtime.
•Remember that runtime merging is only possible in HTML Help (CHM) help files. All other formats use only publish time merging.
•Even with runtime merging, links from child modules to the master module are always OK because the master module is always present.
•It is better to use A-links for all links from the master to child modules and between child modules for runtime merging projects. Then you can always be sure that you will not have problems if you ever need to leave a module out.
•External windows cannot be used across module boundaries in modular help with HTML Help. You cannot make a link that opens a topic from another help file in an external window. This is a restriction of HTML Help.
In modular projects you can create normal links between topics in different modules in almost exactly the same way as between topics within a normal project. You just have to bear in mind that the help file containing the target of the link must be present at runtime (when the help is viewed), otherwise the link will be dead and the user will get an error message.
1.Select the topic in which you want to insert the link – topics in child modules are identified in the Project Explorer with spiky green icons on their TOC entries:
Display for a module configured
for publish time merging
If your child module is configured for runtime merging you cannot edit its topics in the TOC – then you must right-click on the module entry and select Edit Child in the context menu to edit its topics.
2.Proceed as you normally would for inserting a topic hyperlink.
3.In the Hyperlink dialog click on the browse button in the Help File: field and choose the project or published help file containing the topic you want to link to. (It is always preferable to choose a project rather than a compiled help file if possible.)
Never try to create links between different output formats. This will not work!
4.If you choose a project (.hmxz, .hmxp) or HTML Help (.chm) file the topic IDs of the external project or help file will now be displayed in the Topic ID list. Choose the topic (and anchor if applicable) you want to link to and click on OK.
5.Remember that this link depends on the presence of the target help file. If there is any chance that the target file may not be there at runtime don't link to it, or use the A-link method described below.
When using runtime merging it is advisable to define a global "window name" for all the projects in the modular help system. This improves the performance of links to your help from your applications. When you define a global help window, all calls to the help system will open in the same CHM help viewer. Without a global window, you will get additional help viewers opening when calls are made first to one module and then to another.
The global help window option is set in Configuration > Publishing Options > Microsoft HTML Help > Help Windows. You need to set the same global window name in all projects in the modular help system, including the master project.
If you use this option the global help window name must begin with $global_, followed by an identifier consisting only of alphabetic characters. You must use the same global name in all the projects.
Examples of valid global window names:
Important – make sure your window name is unique!
Don't use the standard $global_main name! If you do it is quite possible that some other software on the user's computer will also be using that name and then your help could open in their help window!
Use this method to create links between modules when you are not sure whether the module containing the link target will be present at runtime or not. It creates a link that points to both the main target topic and to an alternative topic in the master help module. If the main target is present the user can select it from the dialog. If it is not present the alternative topic is displayed automatically.
This method only works in HTML Help (the A-link macro is translated automatically when you publish to HTML Help). Use it for creating links between the help files of modular help systems if there is a possibility that the help files containing the target topics may not be present at runtime. This can happen when you use runtime merging and choose not to include one or more of the help files in your distribution.
Step 1: Prepare the alternative topic in the master project
The alternative topic should be in the master project because this is the only help file that is always present in a runtime-merged modular help system.
1.Open the master help project and choose or create the alternative topic that you want the user to be able to view when the other help file module containing the target topic is not available. This can be any topic including a topic in the Topic Files section that does not have a TOC entry.
2.Select this alternative topic in the Project Explorer, display its tab and enter a unique A-keyword in its A-Keywords: field.
Step 2: Prepare the target topic in the child project
1.Select the topic you want to link to in the child project.
2.Display the topic's tab and enter the same A-keyword as above in its A-Keywords: field.
This A-keyword should only be used in these two topics. If you use it in any other topics in any module these topics will also be displayed in the link list.
Step 3: Create the link
1.Open the module in which you want to create the link. This can be a master module or another child module.
2.Select the topic where you want to create the link and open the Insert Hyperlink dialog.
3.Select the Script Link option on the left, then select Winhelp macro.
4.Enter Alink() in the Script: field and type the keyword between the parentheses. If your keyword is "about widgets" the dialog would look like this:
If the target help file is not present when the user clicks on the link the alternative topic will be displayed automatically. If the target topic is present a dialog will be displayed in which the user can select either the target topic or the alternative topic.
This is just a very simple example to show you how this solution works in principle. In practice you can also make more complex solutions, using more alternative topics and more keywords. If you use multiple keywords remember to separate them with semicolons, like this:
Alink(about widgets;troubleshooting;widget solutions)
Modular Projects (Reference)