Modular help

OmniHelp supports modular Help in a way very similar to that used by HTML Help and WinHelp. The main Help project must include a setting in ohproj.js that describes each subproject; for example:

var mergeProjects = [
["oh8",0,0,0,["htmlref","ag*"]],
["oh11",0,0,51,["htmllink","ah*"]]]

where for each subproject, the items included are:

The subproject name, as in "oh8"

A zero to indicate unmerged status

A zero for the size of the subproject (filled in later)

The location in the main TOC sequence of the contents entry for the subproject, the point at which it is inserted into the main project

A list of files contained in the subproject, used when a file that is part of the main project links to a file outside that project to determine if the file about to be loaded is known to be part of the subproject

The main project must also have an entry in .ohc showing the subproject’s position in the Contents:

[2,"8 HTML Reference","*oh8"],

where the three elements are:

contents level number

title to be displayed in the Contents

name of the subproject; the asterisk identifies it as a subproject entry.

A subproject is loaded into the main project in three circumstances:

when a user clicks a link to a file that is not part of the current project, and the name of that file appears in the file list of a subproject in the mergeProjects setting

when a user clicks a Contents entry that specifies a subproject name

at initial load, for all subprojects, if the setting mergeFirst=true is in the .ohx.

Subprojects are loaded one at a time, under control of JavaScript code in ohmerge.js, which is part of the ohctrl.htm set. The merge process does the following:

integrates the full contents of the subproject’s data files with the main project, seamlessly, as if they had always been one project

merges the contents of the subproject’s mergeProjects setting, so that any subprojects included in the previous subproject are now included in the main project.

Subproject merging can be nested to any degree. A newly merged subproject is checked to make sure it does not include as a subproject the original main project, or any other already loaded subproject; if either is the case, the duplicate entry is quietly removed from both mergeProjects and Contents.

When mergeFirst is set to merge all projects at load time, the process is carried out in a depth-first recursive fashion until all subprojects have been loaded. Any that cannot be found are marked as unloadable and are not attempted again; the entry is removed from the Contents. This permits including entries for subprojects that may not exist yet.

All subproject files must be in the same directory as the main project files. Files may be shared between two or more projects; only one copy of a shared file is needed. This sharing can include the oh*.htm and oh*.js files. Because the project-specific files for two projects always have different names, there are no name clashes with this system.

In Mif2Go, the location for a subproject Contents entry is marked with a FrameMaker HelpMerge marker that contains the subproject name. The text to display for the link, and other subproject details, are specified by the user as settings in the mif2htm.ini configuration file. The Mif2Go [Automation] facility can place the needed project files into a shared “wrap” directory, and archive them in a single .zip.