The helpset file name must be unique, so we use the filename convention<groupId>-<artifactId>-helpset.xml. Dots in the groupId shall be replaced by dashes '-'
The "position" defines where the help will appear. To choose a position please refer to the "Menu organisation" bellow
3 Create the helpset.xml next to the layer.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE helpsetref PUBLIC "-//NetBeans//DTD JavaHelp Help Set Reference 1.0//EN" "http://www.netbeans.org/dtds/helpsetref-1_0.dtd">
<helpsetref url="nbdocs:<groupId>/<artifactId>/docs/help.hs" merge="true"/>
It is important that the path to helpset is derived from the <groupId> and the <artifactId> as defined in the pom file of the module. For the snap-aatsr-sst module the path must be /org/esa/snap/snap/aatsr/sst/docs/help.hs.
In this case the term 'snap' is not accidentally duplicated. It is needed. The group Id ends with 'snap'and the artifactId starts with 'snap'. This might be different in your case.
While the docs folder is necessary, the name of the helpset file can be freely chosen. As convention we want to name it "help.hs".
4 Add the help content.
It must be added in a folder named javahelp which must be created under src/main. Here, create the path which is given in the helpset.xml above. It is also mandatory that the path ends with the docs folder. Finally, you end up with a path for the sst example which looks like src/main/javahelp/org/esa/snap/snap/aatsr/sst/docs/help.hs.
In the docs folder you can place the javahelp content as normal:
help.hs references all help files (map.j,m toc.xml, search, ...)
maps.jhm make the links between help page id and urls
toc.xml is the table of content, it lists the pages to display and menu entries, telling what page is displayed where. To add a help page to an existing help menu it must match the menu organisation bellow. For example, to add a geometric processor the toc.xml file could look like that:
Where myGeometricProcessor is the id of the help page referenced in the map.jhm file. For more information about javahelp see jhug.pdf
Tips and Tricks
Opening external links
It is possible to open external web help in the default web browser instead of the javahelp window. For this, the external links need to be changed, by example for the BeamDataSources.html page, change
The dependency org-netbeans-modules-extbrowser must be added to the Platform application.
Unfortunately repeating the link as fall back within the object tag is not working in NetBeans. Actually, it should be used as an alternative if the BrowserDisplayer is not available, e.g. the page is displayed in a normal web browser. Using a URL in the alternative link seems to break the javahelp. When running the jhindexer an exception is thrown like java.lang.ArrayIndexOutOfBoundsException: -845100606
The following tree represents the help menu. When the help menu item is followed by a number, it represents the position of this item as specified in the layer.xml file. The relative position of two items in the same sub-menu is determined by this number, the lowest number goes higher in the menu. These number must be unique.