19.12.3 Providing TOC placeholders for OmniHelp subprojects

Place a HelpMerge PI marker in your main-project DITA document for each subproject listed in the [HelpMerge] section, to:

Insert the HelpMerge PI marker between two main-project topics, in either of the following places:

Do not place the HelpMerge PI marker at the very beginning of the main project, and do not include duplicate HelpMerge PI markers for the same subproject.

The content of the HelpMerge marker consists of a single-digit contents level number (with respect to the main project TOC) for the top TOC entry of the subproject, followed by a space, followed by the path to the subproject. For example:

1 ../api/LibRef

Add subprojects before the fact

To include merge points for future subprojects that are not yet available, so that the main project does not even need to know whether they exist, at the end of the TOC add extra merge points with dummy subproject names. If you specify load-time merging:

[OmniHelpOptions]
MergeFirst=Yes

any subprojects that are present will be integrated, and any merge point for which a subproject is not present will be removed from the TOC.

Add subprojects after the fact

To provide the marker content after the fact, for a subproject that has already been built or was created without using DITA2Go, insert an entry in the *_ohc.js file for the master project, in the position where you want the subproject entry to appear in the master-project contents. The entry must look like this:

[n,"title","*name"],

where the components are as follows:

n

Contents level for the subproject entry in the master-project contents

title

Title of the subproject

name

Project name of the subproject

The last three items in the following example identify subprojects: that are in a directory different from the parent directory, so a relative path is prefixed to the project name:

var tocItems = [
[1,"Server","aa998290.htm#Xaa998290"],
[2,"Feature 1","aa998295.htm#Xaa998295"],
[2,"Feature 2","aa998300.htm#Xaa998300"],
[1,"Connectors","aa998313.htm#Xaa998313"],
[2,"Connector A","*ConnA/ConnA"],
[2,"Connector B","*ConnB/ConnB"],
[2,"Connector C","*ConnC/ConnC"]]

You would also need an item in _ohx.js like this:

var mergeProjects = [ 
["ConnA/ConnA",0,0,4,[]],
["ConnB/ConnB",0,0,5,[]],
["ConnC/ConnC",0,0,6,[]]]

where the 4, 5, 6 are the (zero-based) numbers of the TOC items. This example is for a set-up in which each secondary item is in a subdirectory that has the same name as the project.

See also:

§16.4.3 Setting contents levels for HTML-based Help

§19.12.2 Listing and mapping OmniHelp subprojects

Previous Topic:  19.12.2 Listing and mapping OmniHelp subprojects

Next Topic:  19.12.4 Deciding when to merge OmniHelp subprojects

Parent Topic:  19.12 Merging OmniHelp projects

Sibling Topics:

19.12.1 Understanding the OmniHelp merge process

19.12.2 Listing and mapping OmniHelp subprojects

19.12.4 Deciding when to merge OmniHelp subprojects