title: Using JavaHelp for end user documentation on NetBeans based application, tools or plugins to make it easier?
body: <p>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.</p>
  
  <p>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. </p>
  
  <p>I've figured out far enough how to create a new HelpSet &amp; the XML to HTML relationships. I can hand code in new documents &amp; apply screenshots, but it feels very manual, and I wonder are there any plugins, or tools to facilitate the creation?</p>
  
  <p>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.</p>
  
  <p>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.</p>
  
  <p>Thanks for reading.</p>
  
  <p>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.</p>
  
  <p>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. </p>
  
  <hr>
  
  <p>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.</p>
  
  <p>Under this it will create 6 files:</p>
  
  <pre><code>package-info.java (package info file)
  &lt;modulename&gt;-about.html (As seen HTML help file)
  
  &lt;modulename&gt;-map.xml (creates a connection to the HTML pages (E.G about) to a target, used in making links &amp; building the hierarchy for the table of contents)
  &lt;modulename&gt;-toc.xml (Table of contents XML)
  &lt;modulename&gt;-hs.xml (Specifies the Table of contents view &amp; javax control, &amp; index)
  &lt;modulename&gt;-idx.xml (Controls the index)
  </code></pre>
  
  <p>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.</p>
  
  <pre><code>&lt;modulename&gt;-about.html
  &lt;!--
  To change this template, choose Tools | Templates
  and open the template in the editor.
  --&gt;
  &lt;html&gt;
      &lt;head&gt;
          &lt;title&gt;About Module&lt;/title&gt;
          &lt;link rel="stylesheet" href="nbdocs:/org/netbeans/modules/usersguide/ide.css" type="text/css"&gt;
          &lt;meta http-equiv="Content-Type" content="text/html; charset=UTF-8"&gt;
      &lt;/head&gt;
      &lt;body&gt;
          &lt;h2&gt;About Module&lt;/h2&gt;
          &lt;p&gt;
              &lt;!-- TODO describe your module, add more pages... --&gt;
          &lt;/p&gt;
      &lt;/body&gt;
  &lt;/html&gt;
  &lt;!--
  Tip: to create a link which will open in an external web browser, try:
  &lt;object classid="java:org.netbeans.modules.javahelp.BrowserDisplayer"&gt;
      &lt;param name="content" value="http://www.netbeans.org/"&gt;
      &lt;param name="text" value="&lt;html&gt;&lt;u&gt;http://www.netbeans.org/&lt;/u&gt;&lt;/html&gt;"&gt;
      &lt;param name="textFontSize" value="medium"&gt;
      &lt;param name="textColor" value="blue"&gt;
  &lt;/object&gt;
  To create a link to a help set from another module, you need to know the code name base and path, e.g.:
  &lt;a href="nbdocs://org.netbeans.modules.usersguide/org/netbeans/modules/usersguide/configure/configure_options.html"&gt;Using the Options Window&lt;/a&gt;
  (This link will behave sanely if that module is disabled or missing.)
  --&gt;
  </code></pre>
  
  <p>Anything can be added into the <code>&lt;body&gt;</code> section of the document. I've worked with simple inline CSS and using <code>&lt;FONT&gt;</code> 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 <code>nbdocs:/&lt;yorumodulepath&gt;</code></p>
  
  <p>E.G: <code>Any event added here will show up on the &lt;a href="nbdocs:/com/mymodule/mod1/start/docs/start-about.html"&gt;start page&lt;/a&gt;</code></p>
  
  <p>Images can be linked relatively if they are in the same source package as the javahelp.</p>
  
  <p>E.G: <code>&lt;img src="startPageLogo.png"&gt;</code></p>
  
  <p>The XML files are important because they setup the structure of the help documentation.</p>
  
  <pre><code> &lt;modulename&gt;-map.xml
  </code></pre>
  
  <p>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 &amp; close the JavaHelp tree.
  The structure seems to be: <code>&lt;mapID target="&lt;com.yoruproject.modname" url="&lt;htmlfilename/.html"/&gt;</code></p>
  
  <p>E.G</p>
  
  <pre><code>  &lt;?xml version="1.0" encoding="UTF-8"?&gt;
  &lt;!--
  To change this template, choose Tools | Templates
  and open the template in the editor.
  --&gt;
  &lt;!DOCTYPE map PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 2.0//EN" "http://java.sun.com/products/javahelp/map_2_0.dtd"&gt;
  &lt;map version="2.0"&gt;
      &lt;mapID target="com.mymodule.mod1.start.about" url="start-about.html"/&gt;
      &lt;mapID target="com.mymodule.mod1.start.calevents" url="start-calevents.html"/&gt;
      &lt;mapID target="com.mymodule.mod1.start.backupreminder" url="start-backupreminder.html"/&gt;
  
  &lt;/map&gt;
  
  
  
  
  &lt;modulename&gt;-toc.xml
  </code></pre>
  
  <p>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:</p>
  
  <pre><code> &lt;toc version="2.0"&gt;
          &lt;tocitem text="Top Category"&gt;
              &lt;tocitem text="SubItem" target="com.mymod.mod1.start.about"/&gt;
              &lt;tocitem text="SubCategory"&gt;
                  &lt;tocitem text="SubCategoryItem1" target="com.mymod.mod1.start.backupreminder"/&gt;
                  &lt;tocitem text="SubCategory2" target="com.mymod.mod1.start.about"&gt;
                      &lt;tocitem text="SubCategoryItem2" target="com.mymod.mod1.start.classifyreminder"/&gt;
                  &lt;/tocitem&gt;
       &lt;/tocitem&gt;
      &lt;/tocitem&gt;
  &lt;/toc&gt;
  </code></pre>
  
  <p>Here's an example of a full file:</p>
  
  <pre><code>    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
  &lt;!--
  To change this template, choose Tools | Templates
  and open the template in the editor.
  --&gt;
  &lt;!DOCTYPE toc PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp TOC Version 2.0//EN" "http://java.sun.com/products/javahelp/toc_2_0.dtd"&gt;
  &lt;toc version="2.0"&gt;
      &lt;tocitem text="Start Page"&gt;
          &lt;tocitem text="Getting Started" target="com.mymodule.mod1.start.about"/&gt;
          &lt;tocitem text="Calendar Events" target="com.mymodule.mod1.start.calevents"/&gt;
          &lt;tocitem text="Notification Pane"&gt;
              &lt;tocitem text="Backup Reminders" target="com.mymodule.mod1.start.backupreminder"/&gt;
              &lt;tocitem text="New Classification Downloads" target="com.mymodule.mod1.start.backupreminder"/&gt;
          &lt;/tocitem&gt;
      &lt;/tocitem&gt;
  &lt;/toc&gt;
  
  
  
  
  
  
  
  &lt;modulename&gt;-hs.xml
  </code></pre>
  
  <p>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).</p>
  
  <pre><code>    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
  &lt;!--
  To change this template, choose Tools | Templates
  and open the template in the editor.
  --&gt;
  &lt;!DOCTYPE helpset PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 2.0//EN" "http://java.sun.com/products/javahelp/helpset_2_0.dtd"&gt;
  &lt;helpset version="2.0"&gt;
      &lt;title&gt;HMSStart Help&lt;/title&gt;
      &lt;maps&gt;
          &lt;homeID&gt;com.mymodule.mod1.start.about&lt;/homeID&gt;
          &lt;mapref location="start-map.xml"/&gt;
      &lt;/maps&gt;
      &lt;view mergetype="javax.help.AppendMerge"&gt;
          &lt;name&gt;TOC&lt;/name&gt;
          &lt;label&gt;Table of Contents&lt;/label&gt;
          &lt;type&gt;javax.help.TOCView&lt;/type&gt;
          &lt;data&gt;start-toc.xml&lt;/data&gt;
      &lt;/view&gt;
      &lt;view mergetype="javax.help.AppendMerge"&gt;
          &lt;name&gt;Index&lt;/name&gt;
          &lt;label&gt;Index&lt;/label&gt;
          &lt;type&gt;javax.help.IndexView&lt;/type&gt;
          &lt;data&gt;start-idx.xml&lt;/data&gt;
      &lt;/view&gt;
      &lt;view&gt;
          &lt;name&gt;Search&lt;/name&gt;
          &lt;label&gt;Search&lt;/label&gt;
          &lt;type&gt;javax.help.SearchView&lt;/type&gt;
          &lt;data engine="com.sun.java.help.search.DefaultSearchEngine"&gt;JavaHelpSearch&lt;/data&gt;
      &lt;/view&gt;
  &lt;/helpset&gt;
  </code></pre>