More Advanced Procedures > Working with Modular Help Systems

Creating a modular project is just as easy as adding a topic to a project. Once you have added the child project its TOC is displayed as part of the current project's TOC and you can edit it directly if you turn off read-only mode (see below).

When you compile the master project the entire TOC of the child project is inserted in the master TOC at the point where you insert the child project in the master TOC tree.

See Modular Projects in the Reference section for some more background information on modular help systems.

Productivity Tip

By default child modules are inserted in read-only mode. This is recommended for multi-user editing, otherwise all topics in child projects will be locked for all users. You can turn off read-only mode in Configuration > Common Properties > Miscellaneous.

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 and Winhelp 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.

Display for a project inserted <br>
with publish time merging

Display for a project inserted
with publish time merging

Display for a project inserted <br>
with runtime merging

Display for a project inserted
with runtime merging

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 of the child's topic files directly. Only the topic files 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) and Winhelp (HLP) 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) and Winhelp (HLP). In all other output formats the master and children projects are always published together as one large help project, which is the equivalent of publish time merging.

When you insert a module in runtime mode it will only be exported to HTML Help and Winhelp. If you want to export 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 exported 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.