A master project is a normal Help+Manual project. The only thing that makes it a "master" is the fact that it contains child projects. You can create either an "empty" master project or a master project with content:

•An empty master project is a project without any topics of its own. It is simply a framework for handling your child projects, and all the items in its TOC are child projects.

•A master project with content also has its own topics. Your child projects are inserted in the TOC along with the master project's own topics.

This distinction is actually a little arbitrary. You can always add topics to the master project at any time, even if it is empty when you start. The only thing you need to remember is that the master project's own topics will always be included in the output.

1.Click at the point in the master project's TOC where you want to insert the child project (module).

2.Select Add Topic in Project > Managing Topics and then select the Include Help Project option.

3.In the Project File: field click on the Browse button and select the .hmxz or .hmxp project file you want to include.

Merge content on publishing: If you select this mode the external project's contents will be displayed in the TOC of the current project and can be edited directly if you turn off read-only mode (see below). Merged projects are still stored externally and their topics are identified by small green icon in the TOC.

Merge content at runtime: This is for HTML Help only and just inserts a placeholder in the TOC. The projects must be edited and published separately and are only merged when the user views them if the help files are all present in the same folder.

4.Click on OK to insert the child project in the TOC.

When you are merging your modules on publishing it is possible to include an entire project module in your publishing output without including it in the TOC. In supported output formats all the topics of the module will then be present, but only accessible via hyperlinks in your other topics,  and the full-text search and keyword index (CHM, WebHelp, eWriter, VS Help).

How this works

This is the same as including a single topic without a TOC entry by creating it directly in the Project Files > Topic Files section in the Project Explorer, or by deleting its TOC entry without deleting the associated topic file. The only difference is that this then applies for all the topics in the project module.

The Merged Projects section in Configuration

When you add a child module in the TOC using the publish-time merge method, Help+Manual automatically creates an entry for it down in Configuration > Merged Projects:

These entries are similar to the entries for topic files in the Project Files > Topic Files section. Just as the TOC entries for normal topics point to the topic files in the Topic Files section, the entries for project modules in the TOC point to topic files of the projects in the Merged Projects section.

The entries in Merged Projects are automatically given the build option None so that their contents are not included in your output when you exclude them from the TOC:

How to include a "hidden" child project in your output

Here too, the method is similar to including a topic without a TOC entry. Instead of adding the module to the TOC, you just right-click on the Merged Projects and select Add Merged Help Project in the context menu displayed.

Change the include options to include the project's topics

When you insert a project module like this its include options will initially be set to None. To include its topics in your output you need to right-click on its entry in Merged Projects and set its include options in the Include in Builds context menu so as to include its topics in the output formats where you want this to happen.

You can also use additional TOCs in your master project in order to create alternative outputs using different combinations of modules and native topics from the master project. You just need to create an additional TOC and insert references to the child modules there.

See Multiple TOCs for details on how to create and manage additional TOCs.

Saving child projects separately

When you select Save As.. in a modular project Help+Manual always saves the master project. You must edit child projects separately if you want to save copies of them.

Publish time merging:

If you choose publish merging the project will immediately be displayed as part of your project's TOC and you can edit its topics directly, as though they were part of the current project. The topics of merged projects are identified with green icons on the TOC entries.

Read-only mode:

By default the project will be inserted in read-only mode to prevent accidental changes. You can activate editing in Configuration > Common Properties > Miscellaneous. If you are using multi-user editing you should leave read-only mode ON, otherwise all the topics of child projects will be locked for all other users as long as you have the master project open.

Runtime merging:

If you choose runtime merging a placeholder is inserted in the TOC in the position in which the child project will be inserted. You can edit the child project by right-clicking on the placeholder and selecting Edit Child Project.

Even when the TOC of the your child project is visible in the master TOC you cannot see all the child's Topic Files and Configuration settings directly. Only the topics with TOC entries are actually displayed in the master TOC. You can access topic files without TOC entries and the child's configuration settings in the Merged Projects section in the Project Explorer:

This section is located right at the bottom of the Configuration section. Note that like the TOC, the files and settings of merged projects are only shown for projects inserted in publish-time merging mode. Runtime-merged projects are just placeholders and are not really part of your project, they must be opened and edited separately.

The merge method for HTML Help (CHM) is selected when you insert the child project. To change it you must remove the child project from the TOC and re-insert it with the other merge method.

1.Select the main module item in the Project Explorer and press DELETE or select Add Topic > Delete in Project > Manage Topics.

2.Insert the same module again, selecting the other merge method.

Note that merge options are only relevant for HTML Help (CHM). In all other output formats the master and child projects are always published together as one large help project, which is the equivalent of publish time merging.

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:

$global_main_mycompany
$global_widgethelp

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!

When you insert a module in runtime mode it will only be published to HTML Help (CHM).  If you want to publish the same module to other formats you must insert it in your TOC a second time in publish-time mode. When you do this you should also set the include options for each version so that the correct version gets published automatically depending on the output format you choose:

Setting the include options:

Just right-click on the main module "node" (spiky green icon) in the TOC, select Include in Builds in the context menu and then set the include options appropriately. Make sure that you set the options so that it is not possible to export both versions together!

You can also access the include options in Manage Topics > Change in the Project tab. See Conditions and Customized Output for more details on using include options.