This step by step guide describes how to migrate the help system of the BEAM module to the SNAP/NetBeans help system. It supposes the help dependant modules like the NetBeans Platform application and the SNAP-UI module are configured to display the NetBeans Help system which is not the case at the moment.
The helpset file name has to be unique, so we use the filename convention<groupId>-<artifactId>-helpset.xml. Dots in the groupId shall be replaced by dashes '-'
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>. For the snap-aatsr-sst module the path must be /org/esa/snap/snap/aatsr/sst/docs/help.hs. (No, snap is not accidentally duplicated. It is needed.) 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".
For the help content a folder named javahelpmust be created in 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 help content as normal. So simply move the existing content to this place.
This way is preferred over the first provided that your module is already dependent on the NetBeans platform, Otherwise try to stay with the first one described above.
Add the following dependencies in the pom.xml file :
If you want to reference one page on a module from an other module you have to use the classpath. This supposes the class-paths are different between modules, which is the correct way to have class-paths in general. By example for the SNAP Graph Builder project, move the help files in the ressources folder form docs.help to org.esa.snap.gpf.ui.docs. With the change of path the indexer "maven-javahelp-plugin" is not working anymore, but NetBeans takes care of this.
Add a « package-info.java » file in the docs source folder, by example for the SNAP Graph Builder project: Create the org.esa.snap.gpf.ui.docs source package and add the package-info.java file with the following content:
@HelpSetRegistration(helpSet = "help.hs", position = 3633)
Remarks: org.esa.snap.gpf.ui.docs is the path in the ressource folder where HelpSet file can be found. As convention we want to name the HelpSet file always "help.hs".