Help System Migration

Owned by Nicolas Ducoin (Unlicensed)
Last updated: 2016-05-02 by Marco Peters

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

Resources