How to add help to a module

Owned by Nicolas Ducoin (Unlicensed)
Last updated: 2021-02-02 by Marco Peters
4 min read

Purpose

This page is a step by step guide to add help to a module. This help will be displayed in the help menu of the SNAP application.

Step by step guide



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 or update the layer.xml 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 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:

toc.xml
<?xml version='1.0' encoding='ISO-8859-1' ?> <!DOCTYPE toc PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp TOC Version 2.0//EN" "http://java.sun.com/products/javahelp/toc_2_0.dtd"> <toc version="2.0" categoryclosedimage="folder" categoryopenimage="folder" topicimage="doc"> <tocitem text="Data Processors"> <tocitem text="Geometric operations"> <tocitem text="My geometric processor" target="myGeometricProcessor"/> </tocitem> </tocitem> </toc>

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

to



Remark

  • 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

  • See:

Creating a link between pages of different modules

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

should be replaced by



Resources

Menu organisation

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.

  • General: 1000

    • Overview

    • Definition

    • Data Sources

    • BEAM-DIMAP Format

    • The 'pconvert' Tool

  • Application: 2000

    • Introduction

    • Menus and Toolbars: 2100

      • Menus bar

        • File

        • Edit

        • View

        • Tools

        • Processing

        • Window

        • Help

      • Toolbar

    • Product View: 2200

      • Product Browser

      • Imaging Tools

      • Analysis Tools

    • Import & Export: 2300

      • Import raster data: 2310

        • SAR: 2315

        • GeoTiff: 2320

        • Spot: 2330

        • RapidEye: 2331

        • Envi: 2340

        • NASA Ocean Color: 2350

      • Import vector data: 2360

      • Export raster data: 2370

      • Other exports: 2380

      • Extract pixel value: 2395

    • Tools: 2400

      • Create band from Math Expression: 2410

      • Graph Tools: 2420

      • ... (Tools menu)

      • Plugins

      • Preference

      • External Tools: 2480

  • Command Line Interface: 3000

    • GPF Overview

    • GPF Graph Processing Tools

    • GPF Operator Index

  • Processors: 4000

    • Pre-processing: 4010

      • MERIS L1B Radiometry Correction: 4020

      • Cloud probability processor: 4025

    • Geometric Operations: 4100

      • Collocation: 4110

    • Image Analysis: 4200

      • Cluster analysis: 4210

      • Image analysis: 4220

    • Land Processing: 4300

      • NDVI: 4310

      • SMACS Processor: 4350

    • Water Processing: 4400

      • SST Processor: 4410

      • FLH/MCI Processor: 4420

    • Level 3 Binning: 4700

  • SAR Processing: 5000