How to Create JavaHelp in a Mavenized NetBeans Platform Application

There isn't a JavaHelp template for Maven-based NetBeans Platform modules, hence you need to set up JavaHelp yourself. It's a bit tricky, involving several different parts that can go wrong easily (which is why a JavaHelp template is so handy). Here's instructions on how to set up JavaHelp in your Maven-based NetBeans Platform modules.

Do the following:

1. In each module that needs to provide a JavaHelp set, add this line to the manifest:
   

   OpenIDE-Module-Requires: org.netbeans.api.javahelp.Help

2. In the POM of the container project (i.e., NOT the application project and NOT a functionality module project), add the "dependencies" section in the definition of the "org.codehaus.mojo", while setting the "version" to 3.0:
   

   <plugin>
       <groupId>org.codehaus.mojo</groupId>
       <artifactId>nbm-maven-plugin</artifactId>
       <version>3.0</version>
       <extensions>true</extensions>
       <dependencies>
           <dependency>
               <groupId>javax.help</groupId>
               <artifactId>javahelp</artifactId>
               <version>2.0.02</version>
           </dependency>
       </dependencies>
       <configuration>
           <brandingToken>${brandingToken}</brandingToken>
           <cluster>foobar</cluster>
       </configuration>
   </plugin>

   Note that the "version" is set to 3.0. I could not get JavaHelp to work for 3.1 or 3.2 (the default in 6.9+) and had to revert to 3.0. Maybe someone can correct me on this point somehow.

   Make sure that the POMs in the other projects (i.e., application project and functionality module projects) do not have their own definition of "org.codehaus.mojo". I.e., the container project should handle this definition for the whole application.

3. You have now configured the application to use JavaHelp and have indicated each module that will provide JavaHelp. In each of those modules, you now need to provide JavaHelp content. The simplest approach for this is to create an Ant-based NetBeans Platform module. Then, use the wizard available for Ant-based NetBeans Platform projects for the creation of JavaHelp sets. Then copy the files that are generated into your Maven-based NetBeans Platform project:

   

   Note the following in the screenshot above. The "resources" folder contains the "module1-helpset.xml" file, which references the files in the "src/main/javahelp" folder by means of having the following content:

   <?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:/org/demoapp/demomodule1/docs/module1-hs.xml"/>

   And note that the "layer.xml" file above has this folder added:

   <folder name="Services">
       <folder name="JavaHelp">
           <file name="module1-helpset.xml" url="module1-helpset.xml">
               <attr name="position" intvalue="3818"/>
           </file>
       </folder>
   </folder> 
   

   The folder "src/main/javahelp" is new, I created that myself, by copying that folder from the Ant-based NetBeans Platform module. That's the place where you will now create all your help topics within the Mavenized application. The Map file lists the identifying keys of the help topics, the TOC lists those keys that define the table of contents, and the Index does the same to define the index of the helpset.

That's all you need. Now you have JavaHelp working in your Mavenized NetBeans Platform application: