## Merging Helpsets

The JavaHelp system provides a mechanism for merging multiple helpsets into a single helpset. You use the merge functionality to merge a helpset's views (TOC, index, glossary, favorites, and full text search) into those of an existing helpset, known as the master helpset.

An example of this functionality is a suite of applications, each with its own helpset. Each time the customer installs a new application that is part of the suite, its help information is merged with the help information in the currently installed applications in the suite.

Merging of helpsets can be done statically, by specifying helpsets in the XML code of a master helpset's helpset (`.hs`) file, or dynamically, by writing code in a Java program that uses the JavaHelp software API. The type of merge your software performs depends on the structure of your applications. For example:

- If you know which helpsets could be available, as you would in a suite of applications, you might prefer to perform a static merge, which merges specific, named helpsets if they are installed.
- If you do not know which helpsets might be available, as might be the case with a developer platform that could have any number of modules or plugins, you might prefer to do a dynamic merge.

When a helpset is merged, there are four types of merges that can be performed for each view: SortMerge, UniteAppendMerge, AppendMerge, and NoMerge. Each type of view has its own default merge type. The help author can override a view's default merge type in the helpset (`.hs`) file by setting a view's `mergetype` property. (For example, see the TOC and Index views defined in the example under Helpset File Format.) The help writer can also set a specific merge type for an element of a TOC, an index, or a glossary. (For example, see the sample TOC in Table of Contents File.)

For more information on dynamic merging of helpsets, see the Developer topic Merging Helpsets Dynamically.

The rest of this section covers various aspects of setting up helpsets for merging, which can be done by a help author without the need for Java programming.

### The Master Helpset

When merging helpsets, there must be an initial helpset into which all other helpsets are merged. This initial helpset is called the master helpset. This helpset can simply be the first one installed, or it can be a specially designed dataless master helpset. All other helpsets are merged into the master helpset.

The master helpset controls which views can be merged. For example, if the master helpset does not have a Glossary view, but a helpset being merged does have such a view, the Glossary view is not displayed in the merged helpset.

The master helpset can be an actual, functioning helpset or it can be empty (dataless). A dataless master helpset defines a set of views that do not contain data (there is no `<data>` tag specified for the views). The dataless master helpset serves as a container into which subhelpsets can be merged. You might use a dataless master to ensure that a set of views is shown in the merged helpset.

For example, the following code defines a dataless master helpset for a suite of applications. The helpset does a static merge: it declares a series of subhelpsets and the JavaHelp system merges those helpsets if they are installed on the user's system.

    <?xml version='1.0' encoding='ISO-8859-1' ?>
       <!DOCTYPE helpset
         PUBLIC
         "-//Sun Microsystems Inc.//DTD
          JavaHelp HelpSet Version 2.0//EN"
          "http://java.sun.com/products/javahelp/helpset_2_0.dtd">

       <helpset version="2.0">
          <!-- title -->
          <title>JavaHelp System User's Guide</title>

          <!-- views -->
          <view>
             <name>TOC</name>
             <label>Table Of Contents</label>
             <type>javax.help.TOCView</type>
          </view>

          <view>
             <name>Index</name>
             <label>Index</label>
             <type>javax.help.IndexView</type>
          </view>

          <view>
             <name>Search</name>
             <label>Search</label>
             <type>javax.help.SearchView</type>
          </view>

          <subhelpset location="app1.hs" />
          <subhelpset location="app2.hs" />
          <subhelpset location="app3.hs" />
          <subhelpset location="app4.hs" />

       </helpset>

### Understanding Merge Types

The JavaHelp system provides four merge types that control how helpsets are merged: `javax.help.UniteAppendMerge`, `javax.help.``SortMerge`, `javax.help.AppendMerge`, and `javax.help.NoMerge`. Each view of a helpset (TOC, index, search, glossary, and favorites) has a default merge type that can be overridden by the help author in the helpset's Helpset (`.hs`) file by setting the `mergetype` attribute for that view, as described later in Using Merge Types. (As also described in that section, it is possible to set a merge type for an element of a view, such as an index entry.)

When a helpset is merged into a master helpset, each view is merged according to the merge type that has been set for it.

#### `javax.help.UniteAppendMerge`

This merge type preserves the hierarchy of the master view by merging matching elements at the same level into one element, and then merging and sorting any sub-elements of the matching elements. Any remaining elements are appended to the end of the view. This type of merging works well for TOC views.

Merged elements can be united into a single element only if they are identical. For example, if there is a folder in the master TOC that has a target (a link to a help topic) and a folder in a helpset being merged that has the same name but a different target, these two folders will appear separately in the merged TOC, with the helpset in parentheses after the folder name. If you want the folders to merge into a single element, they must match exactly (have the same targets or no targets at all).

| UniteAppendMerge is slower than SortMerge and is much slower than AppendMerge. If you do UniteAppend merges with the TOCs of multiple helpsets, you might want to test the merge speed of helpsets that have large TOCs to ensure that the speed is adequate for your users.

UniteAppendMerge cannot detect if a navigator (for example, a TOC) that is being merged has entries in it that duplicate each other. If you do not want duplicate entries in the merged TOC, you must ensure that the TOC for each helpset is constructed properly and has no entries that duplicate each other. (An example of duplicated entries is a TOC that lists the same entry in more than one place for organizational purposes).

In the following example from the New Merge sample helpset, there is a master TOC with place holders for specific topics in the TOCs of the helpsets that the help writer expected to be merged. The master helpset is dataless. Its purpose is to ensure that the views of the subhelpsets appear in a particular order. The unmerged TOCs look like this:

Master TOC | Vertebrates TOC | Invertebrates TOC

Animal Categories
Vertebrates
Invertebrates

Animal Categories
Vertebrates
Fish
Amphibians
Reptiles
Birds
Mammals
Marsupials
Primates
Rodents
Cetaceans
Animals Like Seals
Pictures `[Sort merge]`
Bat
Bears
Black Bear
Grizzly
Koala
Bird
Crocodile
Dolphin
Elephant
Fish
Frog
Giraffe
Kangaroo
Leopard
Lizard
Monkey
Orca
Seal
Shark
Snake
Wolves
Arctic Wolf
Timber Wolf

Animal Categories
Invertebrates
Protozoa
Echnioderms
Annilids
Mollusks
Arthropods
Crustaceans
Arachnids
Insects
Pictures `[Sort merge]`
Butterfly
Clam
Crab
Dragon
Sea Star
Spider
Sponge
Worms

By applying the UniteAppendMerge rules to the the TOCs being merged, the JavaHelp system produces a merged helpset with the following characteristics:

- The Vertebrates and Invertebrates TOC items appear in the same order as in the master TOC.
- There is a new Pictures TOC item that is appended after the Invertebrates TOC item.
- The invertebrate and vertebrate sub-elements of the Pictures TOC element are sorted canonically. (The Pictures subnode is defined to use Sort and not UniteAppendMerge, which is why all the picture subitems are sorted in the merged TOC below.)

The following table shows the entire merged helpset:

Merged TOC

Animal Categories
Vertebrates
Fish
Amphibians
Reptiles
Birds
Mammals
Marsupials
Primates
Rodents
Cetaceans
Animals Like Seals
Invertebrates
Protozoa
Echnioderms
Annilids
Mollusks
Arthropods
Crustaceans
Arachnids
Insects
Pictures
Bat
Bears
Black Bear
Grizzly
Koala
Bird
Butterfly
Clam
Crab
Crocodile
Dragon
Dolphin
Elephant
Fish
Frog
Giraffe
Kangaroo
Leopard
Lizard
Monkey
Orca
Seal
Sea Star
Shark
Snake
Spider
Sponge
Wolves
Arctic Wolf
Timber Wolf
Worms

#### `javax.help.``SortMerge`

View data is collated at each level of the view according to the helpset's locale collation rules. (The view is sorted canonically.) If there is an entry in the current master or merged helpset that has the same name and ID as an entry being merged, the merged entry is ignored (the two entries become one entry in the merged view). If the names are the same, the helpset title is added in parentheses to the end of the entry.

This merge type is the default type for the Search view. This type of merge is useful when you have information that is collated, such the elements of an Index or Glossary view. It is not useful when you have information that is in hierarchical form, such as a TOC. To use this merge type for the Index and Glossary views, you must override the default type of those views. The previous example does a SortMerge for the Pictures subitems.

| SortMerge is slower than AppendMerge, but faster than UniteAppendMerge. If you do sort merges with the indexes of multiple helpsets, you might want to test the merge speed of helpsets that have large indexes to ensure that the speed is adequate for your users.

SortMerge cannot detect if a navigator (for example, an index) that is being merged has entries in it that duplicate each other. If you do not want duplicate entries in the merged index, you must ensure that the index for each helpset is constructed properly and has no entries that duplicate each other. (An example of duplicate entries is an index with multiple "space" entries added for vertical spacing.)

In the example below, the Edit, File, and Help Menu entries have the same text, but point to different IDs. When the JavaHelp system merges the two, it distinguishes them by adding by the helpset titles `(Java Workshop)`and `(Java Studio)`.

Java Workshop Index | Java Studio Index | Merged Index

Menus
Build Menu
Debug Menu
Edit Menu
File Menu
Help Menu
Toolbars
Edit/Debug Toolbar
Main Toolbar

Developer Resources
Examples
List of Additional Examples
Step-by-step Example
Menus
Edit Menu
File Menu
Help Menu
View Menu
Toolbars
Composition Toolbar
Main Toolbar

Developer Resources
Examples
List of Additional Examples
Step-by-step Example
Menus
Build Menu
Debug Menu
Edit Menu (Java Workshop)
Edit Menu (Java Studio)
File Menu (Java Workshop)
File Menu (Java Studio)
Help Menu (Java Workshop)
Help Menu (Java Studio)
View Menu
Toolbars
Composition Toolbar
Edit/Debug Toolbar
Main Toolbar (Java Workshop)
Main Toolbar (Java Studio)

#### `javax.help.AppendMerge`

This merge type appends the new view data (data in the view being merged) to the end of the existing view data. No attempt is made to merge identical entries or sort the results.

This type of merge was the only one available in version 1 of the JavaHelp software for the TOC and Index views. To maintain compatibility with this earlier version of JavaHelp software, this merge type is the default for these two views. It is also the default merge type for the Glossary view. If you want the resulting merged Index and Glossary views to be sorted canonically, you must set the `mergetype` attribute for these views to `javax.help.SortMerge` in the Helpset file.

#### `javax.help.NoMerge`

No merging is performed: the view does not appear in the merged helpset. This merge type applies to an entire view, not to elements of a view. It is the default merge type for the Favorites view because that view is user-dependent and is stored in a single file in the user's directory.

### Using Merge Types

As described in the previous section, the JavaHelp system provides four merge types that control how helpsets are merged: UniteAppendMerge, SortMerge, AppendMerge, and NoMerge. Each view of a helpset (TOC, index, search, glossary, and favorites) has a default merge type.

The default merge types for each type of view are:

- TOC.`javax.help.AppendMerge`
- Index. `javax.help.AppendMerge`
- Search. `javax.help.SortMerge`
- Glossary. `javax.help.AppendMerge`
- Favorites. `javax.help.NoMerge`

You can override these merge types for an entire view in the Helpset file, or you can specify a merge type for an element of a view, such as an index entry.

#### Specifying Merge Types in the Helpset File

You can override the default merge type for each view in a helpset. For example, you can merge the TOC views by using UniteAppendMerge and the Index views by using SortMerge. To override a view's merge type, you set the `mergetype` attribute for that view in the view's Helpset (Hs) file.

When a helpset is merged into a master helpset, each view is merged according to its default merge type or the merge type that you have set for it.

For example, a merge type that works well with indexes is SortMerge. The following code shows how to specify this merge type for an index:

    <view mergetype="javax.help.SortMerge">
          <name>Index</name>
          <label>Index</label>
          <type>javax.help.IndexView</type>
          <data>AnimalsIndex.xml</data>
       </view>

#### Specifying Merge Types in the View Files

You can override the view's merge type for each element of a TOC or Index view. Unless overridden again, the merge type definition applies to any subitems of the entry.

- In a TOC, the `<tocitem>` tag supports the `mergetype` attribute.

  In the following example, the `Release` `Information` entry and its three subitems all have the `javax.help.SortMerge` merge type:

  `<tocitem text="Release Information" mergetype="javax.help.SortMerge">`
  `image="chapter" target="rel.release">
  <tocitem text="Contents of the Release"
  image="topic" target="rel.contents"/>
  <tocitem text="Requirements"
  image="topic" target="rel.requirements"/>
  <tocitem text="Changes Since the 1.0 Release"
  image="topic" target="rel.changes"/>
  </tocitem>
  `

- In an index, the `<indexitem>` tag supports the `mergetype` attribute.

  In the following example, the `context` `sensitive` `help` entry and its three subitems all have the `javax.help.UniteAppendMerge` merge type:

  `<indexitem text="context sensitive help" <br>`
  `mergetype="javax.help.UniteAppendMerge">
  <indexitem text="window-level help"
  target="auth.csh.window-level" />
  <indexitem text="field-level help"
  target="auth.csh.field-level" />
  <indexitem text="menu help"
  target="auth.csh.menu" />
  </indexitem>`

### Merging Helpsets Statically

You can specify which help sets to merge in two ways:

- Dynamically. You can write Java code that searches for helpsets and uses the JavaHelp software APIs to merge any that finds. Since this is a programming task and not something a help author is expected to do, this technique is described separately in the Developer topic Merging Helpsets Dynamically.
- Statically. You can add a `<subhelpset>` tag to the master helpset file to explicitly add helpsets. If the IDE does not find a specified subhelpset, it ignores the tag.

To merge helpsets statically, add `<subhelpset>` tags to a master helpset file to specify other helpsets that you want to merge with the original helpset. The merge operation is performed whenever the containing helpset is instantiated.

In the following simple example, `HelpSet2` is merged with `HelpSet1` to produce the unified TOC display shown below the code sample:

    -HelpSet1.hs-
       <?xml version='1.0' encoding='ISO-8859-1' ?>
       <!DOCTYPE helpset
         PUBLIC
         "-//Sun Microsystems Inc.//DTD
          JavaHelp HelpSet Version 2.0//EN"
         "http://java.sun.com/products/javahelp/helpset_2_0.dtd">
       <helpset version="2.0">
          <title>HelpSet 1</title>
          <maps>
            <homeID>hs1_file</homeID>
            <mapref location="hs1.jhm" />
          </maps>
          <view mergetype="javax.help.UniteAppendMerge">
             <name>TOC</name>
             <label>Table Of Contents</label>
             <type>javax.help.TOCView</type>
             <data>hs1TOC.xml</data>
          </view>
         <subhelpset location="HelpSet2.hs" />
       </helpset>

    -HelpSet2.hs-
       <?xml version='1.0' encoding='ISO-8859-1' ?>
       <!DOCTYPE helpset
         PUBLIC
         "-//Sun Microsystems Inc.//DTD
          JavaHelp HelpSet Version 2.0//EN"
         "http://java.sun.com/products/javahelp/helpset_2_0.dtd">
       <helpset version="2.0">
          <title>HelpSet 2</title>
          <maps>
            <homeID>hs2_file</homeID>
            <mapref location="hs2.jhm" />
          </maps>
          <view mergetype="javax.help.UniteAppendMerge">
             <name>TOC</name>
             <label>Table Of Contents</label>
             <type>javax.help.TOCView</type>
             <data>hs2TOC.xml</data>
          </view>
       </helpset>

Unified TOC Display

A static merge has the following special features:

- The helpset that contains the `<subhelpset>` tag is considered to be the master helpset. All helpsets are merged with the master helpset.
- When helpsets are merged, only views with the same name (`<name>` tag) as a view in the master helpset file are merged. Note that in the example above, both views are named "TOC". Any views in the subhelpsets that do not match the views in the master helpset are not displayed.
- Multiple `<subhelpset>` tags can be included in a helpset file. Helpsets are appended in the order in which they occur in the helpset file. If a helpset specified in a `<subhelpset>` tag is not found, it is ignored and no error is issued.
- The `<subhelpset>` `location` attribute takes a URL as its argument.