Help System Migration

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.

Step-by-step guide

1. Remove the following plugin in the pom.xml file.

   <plugin>
       <groupId>com.bc.maven.plugins</groupId>
       <artifactId>maven-javahelp-plugin</artifactId>
   </plugin>

   This creation of the search index will be done by the nbm-maven-plugin.
   
   

2. Add mvn plugin to the <build>/<plugins> section in the pom.xml file if not already present

   <plugin>             
       <groupId>org.codehaus.mojo</groupId>               
       <artifactId>nbm-maven-plugin</artifactId>             
       <version>3.14</version>
       <extensions>true</extensions>
   </plugin> 

    

    

Without Annotation

Even though the nbm-maven-plugin warns that this way of help set registration is deprecated,

[WARNING] src/main/javahelp/ deprecated; use @HelpSetRegistration instead

there is no other way doing it without introducing unwanted dependencies to NetBeans.

1. Add the following line to the manifest.mf file

   OpenIDE-Module-Layer: org/esa/snap/<artifactId>/layer.xml

   For example: The layer for the module snap-aatsr-sst the layer file should be placed at org/esa/snap/aatsr/sst/layer.xml
   
   

2. Create the layer file in the resources section at the location given above

   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE filesystem PUBLIC "-//NetBeans//DTD Filesystem 1.2//EN"
           "http://www.netbeans.org/dtds/filesystem-1_2.dtd">
   <filesystem>
       <folder name="Services">
           <folder name="JavaHelp">
               <file name="<groupId>-<artifactId>-helpset.xml" url="helpset.xml">
                   <attr name="position" intvalue="3818"/>
               </file>
           </folder>
       </folder>
   </filesystem>

   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 '-'

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>. 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".
   
   

4. For the help content a folder named javahelp must 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.
   
   

With Annotation

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.

1. Add the following dependencies in the pom.xml file :

   <dependency>           
       <groupId>org.netbeans.api</groupId>
       <artifactId>org-netbeans-api-annotations-common</artifactId>
       <version>RELEASE80</version>
   </dependency>
   <dependency>
       <groupId>org.netbeans.api</groupId>
       <artifactId>org-netbeans-modules-javahelp</artifactId>
       <version>RELEASE80</version>
   </dependency>

2. Rename the classspath doc.help

   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)
   package org.esa.snap.gpf.ui.docs;
   
   import org.netbeans.api.javahelp.HelpSetRegistration;

   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".
   
   

   The position must be unique

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 extenal links need to be change, by example for the BeamDataSources.html page, change

<a href="https://earth.esa.int/web/guest/pi-community/apply-for-data">https://earth.esa.int/web/guest/pi-community/apply-for-data</a>

to

 <object classid="java:org.netbeans.modules.javahelp.BrowserDisplayer">
    <param name="content" value="https://earth.esa.int/web/guest/pi-community/apply-for-data">
    <param name="text" value="<html>apply for data</html>">
 </object>

Creating link between pages of different modules

It is possible to create link between pages of different modules, for this it is necessary to specify the full path to the module. One common example is the "BeamOverview".

<a href="../general/BeamOverview.html">

should be replaced by

<a href="nbdocs://org.esa.snap.help/org/esa/snap/help/docs/general/overview/BeamOverview.html">

Resources

• NetBeans Help Guidelines
• NetBeans Maven Platform Tutorial with Helpset Registration