DevFaqHelpGuidelines

(Difference between revisions)
m (How do I link to a page in a separate helpset?)
m (How do I hook up CSH for a dialog or UI element?)
Line 179: Line 179:
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.
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:
 
-
 
-
<pre>-J-Dorg.netbeans.modules.javahelp=-1</pre>
 
For NetBeans IDE 6.0 and after, use:
For NetBeans IDE 6.0 and after, use:

Revision as of 13:30, 9 February 2011

Module Helpset Integration FAQs

Contents


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
maven general org.netbeans.modules.maven 3789
mobility/javahelp Mobility org.netbeans.modules.mobility.javahelp 450
profiler Java profiler org.netbeans.modules.profiler
php.help PHP development org.netbeans.modules.php.help
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.helpset basic web app projects org.netbeans.modules.web.helpset 360
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 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.

Note: You can add the switch to the NetBeans default switches. Edit INSTALLATION_DIRECTORY/etc/netbeans.conf. If you want to risk editing your .conf file, that is!

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>

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:

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:

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo