---

Module Helpset Integration FAQs

How to Create a Help Set in a Module

1. In the IDE, right-click the node of the project to which you want to add the help set and choose New | Other.
2. In the Module Development category, choose JavaHelp Help Set and complete the wizard.

What Modules are the NetBeans Help Sets In?

Module Source Location	Description	Module Name	Position Intvalue
apisupport.project	Module/RCP building help	org.netbeans.modules.apisupport.project	2700
bpel.help	BPEL	org.netbeans.modules.bpel.help	1200
cnd	C/C++	org.netbeans.modules.cnd	850
compapp.help	SOA composite applications	org.netbeans.modules.compapp.capshelp	2200
db	DB support	org.netbeans.modules.db	900
dbschema	DB Schema	org.netbeans.modules.dbschema	1300
identity.profile.ui	identity	org.netbeans.modules.identity.profile.ui	2500
j2ee.platform	J2EE, including general info about registering servers	org.netbeans.modules.j2ee.platform	400
j2ee.sun.appserv81	sun appserver/glassfish integration	org.netbeans.modules.j2ee.sun.appsrv81	1000
j2ee.websphere6	WebSphere 6 plugin	org.netbeans.modules.j2ee.websphere6
java/helpset	general Java apps	org.netbeans.modules.java.helpset	350
mercurial	general	org.netbeans.modules.mercurial	3004
mobility/javahelp	Mobility	org.netbeans.modules.mobility.javahelp	450
profiler	Java profiler	org.netbeans.modules.profiler
ruby.help	Ruby, Rails, JRuby development	org.netbeans.modules.ruby.help	800
sql.help		org.netbeans.modules.jdbc.jdbchelp	2600
subversion	Subversion support	org.netbeans.modules.subversion	1900
tomcat5	tomcat web server help	org.netbeans.modules.tomcat5	600
uml		org.netbeans.modules.uml	1500
usersguide	general IDE help	org.netbeans.modules.usersguide	100
versioning.system.cvss	CVS support	org.netbeans.modules.versioning.system.cvss	1800
visualweb.ravehelp.rave_nbpack	Java web applications	org.netbeans.modules.visualweb.ravehelp.rave_nbpack	375
web.monitor	HTTP monitor	org.netbeans.modules.web.monitor	700
xml.catalogsupport		org.netbeans.modules.xml.catalogsupport	2300
xml.schema		org.netbeans.modules.xml.schema	2000
xml.wsdlui		org.netbeans.modules.xml.wsdlui
xslt.xslthelp	XSLT	org.netbeans.modules.xslt.xslthelp

How do I determine the order in which a help set appears in the help viewer?

The order in which help sets are merged is determined by a position attribute in the help set module's layer file. The higher the number, the lower the position. See the table above for the numbers assigned to the current help sets.

To change the position of a help set:

1. Open the module's XML layer file.
2. Change the "intvalue" value of the help set's "position" attribute.

How do I hook up CSH for a dialog or UI element?

See this document: http://www.netbeans.org/download/4_1/javadoc/JavaHelpAPI/org/netbeans/api/javahelp/doc-files/help-guide.html

You can debug CSH help IDs by running the IDE with one of the following switches. The IDE prints the help ID of each component you press F1 or the Help button in the console/log and tells you if the help ID was not found in the map file.

For NetBeans IDE 5.5 and before, use:

-J-Dorg.netbeans.modules.javahelp=-1

For NetBeans IDE 6.0 and after, use:

-J-Dorg.netbeans.modules.javahelp.level=100

You can view the output straight from the IDE. Choose View | IDE Log File.

How do I link to a page in a separate helpset?

The best way is using the following syntax:

   <a href="nbdocs://module_name/path_to_page_from_javahelp_directory"> 
   Example: <a href="nbdocs://org.netbeans.modules.db/org/netbeans/modules/db/docs/connectdb.html">Connecting to a Database</a><br></pre>

When you use this format, the IDE displays an error message if the module is not installed. Otherwise broken inter-helpset links do not do anything in the IDE.

The module name should be the name of the module containing the helpset. The name is listed in the OpenIDE-Module property of the module's JAR file. See the table above for the names of the most common help modules.

If you know that the module helpset will always be installed (i.e., usersguide helpset) you can use the simple form:

   <a href="nbdocs:/path_from_javahelp_dir">
   Example: <a href="nbdocs:/org/netbeans/modules/db/docs/connectdb.html">

How do I merge helpsets?

Helpsets are merged automatically by the IDE's master helpset. You don't need to specify mergetypes for the views of your helpset.

How do I merge into an existing TOC and index category?

In your TOC file, copy the TOC category structure exactly as it exists in the usersguide module TOC file (http://www.netbeans.org/source/browse/usersguide/javahelp/org/netbeans/modules/usersguide/ide-toc.xml). Then place your listing in the desired category.

For example, say you wanted to list a help file under the Java Project Basics -> Building Java Applications category. You would enter the following in your TOC file:

   <?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">
      <tocitem text="Java Project Basics">
          <tocitem text="Building Java Applications">
              <tocitem text="My Help File" target="my_target" /> 
          </tocitem>
      </tocitem>
   </toc>

"My Help File" would get merged in at the end of the topics in the category.

The same technique works for indexing. To merge into the "databases" index category, do the following:

   <indexitem text="databases" > 
       <indexitem text="MyCoolDB, connecting to" target="connectMyCool" />
     </indexitem>

Are there guidelines for creating TOC and Index entries?

• If possible, try to merge your helpset into the existing TOC categories and index categories. For example, if you are developing a server plugin merge it into the Servers and Databases > Servers category.
• In general, put all of your topics into a TOC category. There should never be individual topic entries as first-level entries in the TOC.
• Don't have your category nodes linked to a topic. If there is a general intro topic for your section, put it as an About page underneath. WRONG:

       <tocitem text="My Cool Plug-in" target="myCoolPlugin">
          ...
       </tocitem>

RIGHT:

       <tocitem text="My Cool Plug-in" >
          <tocitem text="About My Cool Plug-in" target="myCoolPlugin" />
          ...
       </tocitem>

How do I create a glossary item in the help?

Create the glossary page. The page should have an <h6> title in lower case capitalization, for example:

      <h6>standard project</h6>
      <p>A project that uses an IDE-generated Ant script to compile, run, and debug...

Note Glossary topics shouldn't be listed in the Table of Contents. Use the following syntax to link to the glossary page:

      <object classid="java:com.sun.java.help.impl.JHSecondaryViewer">
         <!-- Enter the link to the glossary page below-->
          <param name="content" value="../project/csh/glossary_standard.html">
          <param name="viewerActivator" value="javax.help.LinkLabel">
          <param name="viewerStyle" value="javax.help.Popup">
          <param name="viewerSize" value="400,220">
         <!-- Enter the display text below-->
         <param name="text" value="standard Java project">
          <param name="textFontSize" value="small">
          <param name="textFontFamily" value="SansSerif">
          <param name="textFontStyle" value="italic">
          <param name="textFontWeight" value="bold">
          <param name="textColor" value="blue">
      </object>

How do I make a link to an external web page open in the IDE's external web browser?

Use the following syntax:

      <object classid="java:org.netbeans.modules.javahelp.BrowserDisplayer">
         <!-- Enter the URL below -->
          <param name="content" value="http://www.netbeans.org/kb/41/freeform-config.html">
          <!-- Enter the display text below. The <html> and <u> make the text look like a link. -->
          <param name="text" value="<html><u>http://www.netbeans.org/kb/41/freeform-config.html</u></html>">
          <param name="textFontSize" value="medium">
          <param name="textColor" value="blue">
      </object>

Note When you view the page outside of !NetBeans, this link will not display or will display as a ???

How do I link to the common CSS for the IDE?

Each helpset should use the ide.css that is included in the usersguide module. Linking to the common CSS lets vision-impaired users make changes to the help font and backgroung colors. Use the following link in your HTML pages:

      <link rel="StyleSheet" href="nbdocs://org.netbeans.modules.usersguide/org/netbeans/modules/usersguide/ide.css" type="text/css">

Is there a template for HTML help pages I can use?

Sure is! Here's a few basic templates:

• Procedure page Coming soon
• Glossary page Coming soon

How do I check links between help files and between metadata and help files?

There are special ant targets for this purpose that you can run from inside of the IDE. However, the Ant script has to use JDK 5 (not JDK 6). The easiest way to change this is to have a build of the IDE that use JDK 5 for purposes of link checking.

To check links in individual help sets (including links in and validity of metadata files):

1. Make sure the IDE is running on JDK 5 - http://wiki.netbeans.org/FaqJdkHome
2. Make sure that you have the nbbuild module checked out. You get this automatically if you have a clone of the repository.
3. In your help set, right-click the build.xml file for the help set and choose Run Target > check-javahelp. (If you are unsure about which build.xml file applies to the help set, look at the Module Source Location column of the help set table at the top of this page to determine the location of the build.xml file.)

To check inter-helpset links:

1. Clone the entire NetBeans main repository.
2. Make sure the IDE is running on JDK 5 - http://wiki.netbeans.org/FaqJdkHome
3. Right-click the 'nbbuild' module's build.xml file and choose Run Target > build-nozip. Now the sources are built. Go get coffee. Do not continue with this procedure unless the build succeeds (see Output window for info).
4. Now, on the build.xml file again, choose Run Target > check-javahelpbin.

NOTE - This latter check is based on built modules. If you make or update changes in the files, you have to rebuild the modules before the changes will be recognized by the link check. Running the check-javahelp target for the module that you have updated does the trick (you do not necessarily have to rebuild the whole IDE).

NetBeans also provides the following pages for each major area of functionality:

• Working with Coming soon
• Task Quick Reference Coming soon