Runtime Merging Output From Flare WebHelp Projects

Important WebHelp and WebHelp Plus are deprecated in Flare, which means that they are slated to be removed in a future version.

Use this merging method if you are developing HTML5, WebHelp, or WebHelp Plus and you want to merge the output files from your parent project with the web output files from an external Flare project. This method is useful, for example, if another author is working on the external web project to which you are linking and you only have access to the output files (not the project files).

Before your parent project can be merged with an external Help system, the output folders and files for the external (or "child") project need to be copied to a folder called "Subsystems" in the same location where the parent project is being published. The child's target folder containing these output files also needs to be included at this location.

Example If the parent project's output files are being published to:

C:\MyHelpSystem\Parent\Parent.mcwebhelp

The output folders and files for the child project should be copied to the folder:

C:\MyHelpSystem\Parent\webSubsystems

(e.g., C:\MyHelpSystem\Parent\Subsystems\AnotherHelpSystem\AnotherHelpSystem.mcwebhelp)

In this example, "AnotherHelpSystem" is the target folder that you generated, which holds the output folders and files, and "AnotherHelpSystem.mcwebhelp" is the main output file for the child project that was created. Not only does the main .mcwebhelp output file need to be included in this folder, but also the ancillary output folders and files (e.g., Content, Data, Skin).

You can merge WebHelp outputs using an automatic or manual method.

How to Merge Output From Web Projects (Automatic Method)

  1. Generate the output for the child project.

  2. Open the TOC in the Flare project that will serve as the parent project.

    Note You can also merge projects by linking them from a browse sequence, as well as from a TOC. If you want to do this, simply follow these same steps after opening your browse sequence.

  3. In the TOC Editor, select the TOC entry or book where you want to link the output from the child WebHelp project. (The TOC of the linked project will be inserted at that spot in the parent TOC.)
  4. In the local toolbar of the TOC Editor, click Display properties for the selected item.. The Properties dialog opens.
  5. Click Enter External Help System. The Link to Help System dialog opens.
  6. Click Browse.
  7. In the Files of type field, click the down arrow and select MadCap Web Help Files (*.mcwebhelp). Then find and select the MCWEBHELP output file to which you want to link.

  8. Click OK.

    The full path to the file is displayed in the field.

  9. (Optional) If you want the merged TOC to replace the entry that you selected, do the following:
    1. Select the Advanced tab.
    2. Click the check box labeled When merging, replace node with merged TOC.

    For example, you might have a TOC in your parent project that looks like this:

    If you select the option in this step to replace the node, the merged TOC would look like this in the output:

    And if you do not select this option, your merged TOC would look like this:

  10. In the Properties dialog, click OK.

  11. Build the output for the WebHelp target in your parent project.

    Flare automatically creates the Subsystems folder for you. It also copies the target folder and .mcwebhelp file (along with the ancillary output files and folders) to the appropriate destination. When you open the TOC in the output, you will see the integrated TOC from the linked project.

How to Merge Output From Web Projects (Manual Method)

  1. Generate the output for the child project.
  2. Open the TOC in the Flare project that will serve as the parent project.
  3. In the TOC Editor, select the TOC entry or book where you want to link the output from the child WebHelp project. (The TOC of the linked project will be inserted at that spot in the parent TOC.)
  4. In the local toolbar of the TOC Editor, click Display properties for the selected item.. The Properties dialog opens.
  5. Click Enter External Help System. The Link to Help System dialog opens.
  6. Type the name of the child target and main output file (e.g., AnotherHelpSystem/AnotherHelpSystem.mcwebhelp).
  7. Click OK.
  8. (Optional) If you want the merged TOC to replace the entry that you selected, do the following:
    1. Select the Advanced tab.
    2. Click the check box labeled When merging, replace node with merged TOC.

    For example, you might have a TOC in your parent project that looks like this:

    If you select the option in this step to replace the node, the merged TOC would look like this in the output:

    And if you do not select this option, your merged TOC would look like this:

  1. In the Properties dialog, click OK.
  2. Build the output for the WebHelp target in your parent project.
  3. In the parent Flare project, right-click on the target and select Open Output Folder. Within that folder, manually create another folder and name it Subsystems.
  4. In the child Flare project, select Project > Open Output Folder (if using the ribbon view) or Build > Open Output Folder (if using the menu view).
  5. Copy the target folder to be merged with the parent project.
  6. Paste the target folder within the Subsystems folder that you created in the parent output folder.

What’s Noteworthy?

Note There are occasions when projects cannot be merged because the file name is the same in two or more of the linked projects (e.g., multiple WebHelp projects all named "MyWebProject.mcwebhelp" or multiple Microsoft HTML Help projects all named "MyHtmlHelp.chm"). The way to solve this dilemma is to make sure each linked project has a different output file name. To do this: (1) open the target, (2) select the General tab in the Target Editor, and (3) enter a unique name in the Output File field.

Note If you plan to use Mark of the Web (MOTW) and are merging output from multiple Flare WebHelp projects, make sure you enable MOTW in all of the subprojects to be included in the merge. Otherwise, the output will not load smoothly into the browser window for the user. For more information about MOTW, see Adding Mark of the Web and Microsoft's MSDN website.

Note If you want to create links from content in one project to content in another project, see Inserting Links to External Files—HTML, PDF, Microsoft Office.

Note If you have previously merged Flare projects with WebHelp outputs and then decide to generate WebHelp Plus output from the parent project instead, you must make sure that the child projects linked to the parent contain at least one WebHelp Plus target each. Even if you keep the link from the parent project to a WebHelp target in the child, the child project must also have a WebHelp Plus target.

Note If you merge projects, synonym files will remain separate in each project. For example, if you create synonyms in Project A but not in project B, only the topics from Project A will use the synonyms when users perform searches in the output.