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:
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.
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>
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.UniteAppendMergeThis 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 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.SortMergeView 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.AppendMergeThis 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.NoMergeNo 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.
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:
javax.help.AppendMergejavax.help.AppendMergejavax.help.SortMergejavax.help.AppendMergejavax.help.NoMergeYou 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.
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>
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.
<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>
<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>
You can specify which help sets to merge in two ways:
<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>
|
A static merge has the following special features:
|