java swing netbeans netbeans-plugins javahelp

Using JavaHelp for end user documentation on NetBeans based application, tools or plugins to make it easier?

The shorter top section of this post is what I'm trying to do. The second portion is what's been done so far. It's really long, but you should be able to see what I'm doing from the top piece here. Just check the notes if you're interested in more detail.

I'm building an application using the NetBeans platform as a jump off point. The previous version used JavaHelp for end user documentation. I'm fine with continuing the practice as I write up all the new documentation, but I'm finding a dearth if information on it's use.

I've figured out far enough how to create a new HelpSet & the XML to HTML relationships. I can hand code in new documents & apply screenshots, but it feels very manual, and I wonder are there any plugins, or tools to facilitate the creation?

Doing some Google-foo I find several posts around the topic, but most are relevant back to 2003 and are now dead-ends. Is using JavaHelp out of date? Below I'm outlining what I've done for any edification of people searching for the same thing, and maybe someone can point out an inefficiency in the way I'm doing this.

It's not a terrible approach, but having to add lines to two XML files for each file I upload, then having a long code URL to have to point to each time feels cumbersome for writing this stuff out quickly.

Thanks for reading.

Edit: One thing I do have a problem with. I don't know how to change the initial landing page for the JavaHelp. Right now it says "This lists all documentation loaded with the IDE, click to the left to read through it". That's not going to mean anything to my end users.

Also, I don't know how to change the order of the topics on the left. Right now they don't appear to be in any useful order. I would like to alphabetize, or put them into some sort of useful order.

In Netbeans, right click on the module New->Other click the Module Development select JavaHelp Help Set. This will create a new package under the module. It will follow the naming convention of your module and will append a .docs to the end. E.G org.netbeans.newmodule.docs.

Under this it will create 6 files:

package-info.java (package info file)
<modulename>-about.html (As seen HTML help file)

<modulename>-map.xml (creates a connection to the HTML pages (E.G about) to a target, used in making links & building the hierarchy for the table of contents)
<modulename>-toc.xml (Table of contents XML)
<modulename>-hs.xml (Specifies the Table of contents view & javax control, & index)
<modulename>-idx.xml (Controls the index)

The first HTML file is the initial information page. It's the help file that the end user will read. It's just regular HTML, in a specific format.

<modulename>-about.html
<!--
To change this template, choose Tools | Templates
and open the template in the editor.
-->
<html>
    <head>
        <title>About Module</title>
        <link rel="stylesheet" href="nbdocs:/org/netbeans/modules/usersguide/ide.css" type="text/css">
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    </head>
    <body>
        <h2>About Module</h2>
        <p>
            <!-- TODO describe your module, add more pages... -->
        </p>
    </body>
</html>
<!--
Tip: to create a link which will open in an external web browser, try:
<object classid="java:org.netbeans.modules.javahelp.BrowserDisplayer">
    <param name="content" value="http://www.netbeans.org/">
    <param name="text" value="<html><u>http://www.netbeans.org/</u></html>">
    <param name="textFontSize" value="medium">
    <param name="textColor" value="blue">
</object>
To create a link to a help set from another module, you need to know the code name base and path, e.g.:
<a href="nbdocs://org.netbeans.modules.usersguide/org/netbeans/modules/usersguide/configure/configure_options.html">Using the Options Window</a>
(This link will behave sanely if that module is disabled or missing.)
-->

Anything can be added into the <body> section of the document. I've worked with simple inline CSS and using <FONT> tags have worked so far. It also links to an external CSS file, so I assume that would work too. You can link to other help files by specifying the path. The path will always start with nbdocs:/<yorumodulepath>

E.G: Any event added here will show up on the <a href="nbdocs:/com/mymodule/mod1/start/docs/start-about.html">start page</a>

Images can be linked relatively if they are in the same source package as the javahelp.

E.G: <img src="startPageLogo.png">

The XML files are important because they setup the structure of the help documentation.

 <modulename>-map.xml

This file links up the HTML files to the nbdocs files. This will allow you to create links inside the HTML files to other help file locations and have it properly open & close the JavaHelp tree. The structure seems to be: <mapID target="<com.yoruproject.modname" url="<htmlfilename/.html"/>

E.G

  <?xml version="1.0" encoding="UTF-8"?>
<!--
To change this template, choose Tools | Templates
and open the template in the editor.
-->
<!DOCTYPE map PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 2.0//EN" "http://java.sun.com/products/javahelp/map_2_0.dtd">
<map version="2.0">
    <mapID target="com.mymodule.mod1.start.about" url="start-about.html"/>
    <mapID target="com.mymodule.mod1.start.calevents" url="start-calevents.html"/>
    <mapID target="com.mymodule.mod1.start.backupreminder" url="start-backupreminder.html"/>

</map>




<modulename>-toc.xml

This file controls the structure on the left side of the JavaHelp that the user can use to drill down into different areas of the help documentation. The format goes as:

 <toc version="2.0">
        <tocitem text="Top Category">
            <tocitem text="SubItem" target="com.mymod.mod1.start.about"/>
            <tocitem text="SubCategory">
                <tocitem text="SubCategoryItem1" target="com.mymod.mod1.start.backupreminder"/>
                <tocitem text="SubCategory2" target="com.mymod.mod1.start.about">
                    <tocitem text="SubCategoryItem2" target="com.mymod.mod1.start.classifyreminder"/>
                </tocitem>
     </tocitem>
    </tocitem>
</toc>

Here's an example of a full file:

    <?xml version="1.0" encoding="UTF-8"?>
<!--
To change this template, choose Tools | Templates
and open the template in the editor.
-->
<!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">
    <tocitem text="Start Page">
        <tocitem text="Getting Started" target="com.mymodule.mod1.start.about"/>
        <tocitem text="Calendar Events" target="com.mymodule.mod1.start.calevents"/>
        <tocitem text="Notification Pane">
            <tocitem text="Backup Reminders" target="com.mymodule.mod1.start.backupreminder"/>
            <tocitem text="New Classification Downloads" target="com.mymodule.mod1.start.backupreminder"/>
        </tocitem>
    </tocitem>
</toc>







<modulename>-hs.xml

I did not mess with this file yet. It seems to outline the location of the Table of Contents, the IDX file for the index, and the SearchView file (which was a default Java location).

    <?xml version="1.0" encoding="UTF-8"?>
<!--
To change this template, choose Tools | Templates
and open the template in the editor.
-->
<!DOCTYPE helpset PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 2.0//EN" "http://java.sun.com/products/javahelp/helpset_2_0.dtd">
<helpset version="2.0">
    <title>HMSStart Help</title>
    <maps>
        <homeID>com.mymodule.mod1.start.about</homeID>
        <mapref location="start-map.xml"/>
    </maps>
    <view mergetype="javax.help.AppendMerge">
        <name>TOC</name>
        <label>Table of Contents</label>
        <type>javax.help.TOCView</type>
        <data>start-toc.xml</data>
    </view>
    <view mergetype="javax.help.AppendMerge">
        <name>Index</name>
        <label>Index</label>
        <type>javax.help.IndexView</type>
        <data>start-idx.xml</data>
    </view>
    <view>
        <name>Search</name>
        <label>Search</label>
        <type>javax.help.SearchView</type>
        <data engine="com.sun.java.help.search.DefaultSearchEngine">JavaHelpSearch</data>
    </view>
</helpset>

Solution

What is the number one problem? Is it that the current process is too laborious? I think it would be easier to help if you asked a single clear question at a time. Anyway, here are some tips that might help.

As far as I can tell, development of Sun JavaHelp has ceased. You might want to try Oracle Help instead. It is very similar to JavaHelp, but more actively maintained.

There are commercial authoring tools that help in taking the drudgery out of producing JavaHelp (or Oracle Help). Examples:

Helen: a JavaHelp-only tool that had its latest release in April 2012 (so JavaHelp cannot be dead after all...)
WebWorks ePublisher: a tool that can generate many more help formats besides JavaHelp

Other options are the free XML-based documentation frameworks DocBook and DITA, which both provide stylesheets (see here, and here) that generate JavaHelp from XML sources (I think very little is needed in order to make this work also for Oracle Help).

There are also other (non-JavaHelp) alternatives. For example, DocBook also provides a web-based help format: WebHelp. Perhaps you'll find that interesting.