Building Your NetHelp System

After all your content is written or converted, you need to install and run a tool--the NetHelp Builder --which will automatically generate all additional files for your help system.

After building your NetHelp system, open it up in NetHelp and see how it functions. You need to test, troubleshoot, and fix any errors in your help before finally packaging and delivering it to your users' computers.

In this building phase you will

About the NetHelp Builder

The NetHelp Builder is the primary tool provided by Netscape to build NetHelp systems. It builds the project files, the index data file, and the Table of Contents data file for your NetHelp system. It also allows you to specify the working and installed directories, to set the default window size, and to select international settings. After it generates the files, the Builder copies your completed NetHelp system into your installed directory for testing.

In some ways, using the Builder is analogous to using a help compiler: you run it after you've edited your content files so that you can then see and test your help system. But the NetHelp Builder is significantly different than traditional help compilers in several important ways:

Installing the NetHelp Builder

Follow these steps to install the NetHelp Builder:
  1. Copy the builder directory from the NetHelp 2.0 SDK to your own machine.
  2. Run Communicator and open the builder.htm file from the builder directory you just copied.
  3. You'll see the NetHelp Builder page appear in your browser window. Bookmark this page so that you can easily get to the builder in the future.
Note that you can also serve the builder (for multiple users) from a web server such as Netscape's Fast Track or Enterprise Servers.

Running the NetHelp Builder

Before running the NetHelp Builder you must have Java enabled (it is enabled by default in Communicator). To verify this, go to the Preferences>Advanced dialog box and make sure that you have "Java Enabled" checked.

To run the Builder:

  1. In Communicator, select the NetHelp Builder bookmark to display the tool.
  2. In the " In the "Working Directory" field enter the location, or use the Browse button to find the location, of the working directory. See the explanation on directories for more information on the working directory.
  3. In the "Installed Directory" field enter the location of the \nethelp directory inside your Communicator installation. After building the data files, the Builder will copy your entire NetHelp system to a directory in \nethelp that has the same name as your working directory  For more information about the installed directory, read this section on directories.
  4. In the "NetHelp System Identifier" field enter a unique name for this NetHelp system.  Note that this must be different than the name of other NetHelp 2.0 systems you may create.
  5. In the "NetHelp Window Default Size" fields, you can either leave the default settings or specify the size you want the NetHelp window to display. The default settings are the same as those for this Authoring Guide NetHelp system. (Note that your help users will still be able to resize the NetHelp window).
  6. In the "Collation Order" fields select the country and the language to be used by the Builder when it creates and sorts your Table of Contents and Index entries.
  7. Leave the NetHelp Version button set to "2.0". The 1.0 setting is for backward compatibility with earlier NetHelp versions.
  8. When all the fields are correctly set, select the "Build and Install Project" button. The Builder begins processing and status messages will appear in the lower part of the Builder window. When the word "Done" appears the NetHelp system files are complete and your NetHelp system has been copied to your installed directory for you to use and test.

Builder Notes for UNIX NetHelp

The generated files IdxData.js and CntData.js are case-sensitive on UNIX NetHelp implementations. When copying, moving, and checking these files, be sure to maintain the specific camel-capped case convention so that these files work properly with the NetHelp system on UNIX machines.

If you know that you're only deploying your NetHelp system on PC and/or Macintosh systems, you don't have to worry about this.

When to Run the NetHelp Builder

Since the Builder creates the project files, the Index file, and the Table of Contents file, and copies the NetHelp system to your installed directory, you need to run the Builder whenever you want to see new edits or changes reflected in your NetHelp system. In practice, you'll usually make many changes during an editing or writing session (all in your working directory), and then run the Builder once at the end of that session so you can then open NetHelp and view your changes (from your installed directory).

Keep in mind that you edit in a different directory than the directory from which you view your NetHelp system. Therefore, if you forget to run the Builder you won't see your changes in the viewed help.

About Testing and Fixing

This test section assumes that your content is as you want it and that you've run the Builder to build and install your project. You test your files not in the working directory in which you authored them, but in the installed directory where the Builder put them.

When you find errors in your installed help, you need to fix the errors in the files in your working directory. After you've fixed one or many errors, run the Builder again, and then test again from your installed directory. Usually, you'll need to repeat this process several times to eliminate all the errors in your NetHelp system. The usual test-fix cycle therefore looks like this:

Writing-Building-Testing-Editing Process

  1. Write and edit your help files in your working directory
  2. Run the Builder (which processes your files and moves them to your installed directory)
  3. Test your files from your installed directory.
  4. Make fixes in your help files in your working directory. Repeat this process until the testing reveals no significant errors.

  5. Deliver your NetHelp system.

Testing NetHelp Content

There are many methods you can use to test your NetHelp system, and you should use the best ones for your particular NetHelp system. This procedure is a minimal one that tests how well your content works with the NetHelp 2.0 features: navigation, display, style sheets, table of contents, index, and so on.

Of course, you'll also need to test your content itself to ensure that it is technically correct, grammatically and stylistically appropriate, and that it meets your users' needs, and your usability criteria. You'll also need to test any other extended HTML features you may have used, such as animated GIFs, JavaScript, Java applets, plug-ins, and so forth.  The test procedure shown here doesn't cover these tests, it only covers the NetHelp functionality; but it's a good idea to perform all these content-only tests at the same time you do the NetHelp-content test in this procedure.

For each section in your NetHelp system, perform the following tests. Consult the Troubleshooting Chart to find solutions to the problems you find.

  1. Check that there is no horizontal scrollbar. If there is, you either have a wide graphic or you have a long text string. Edit your graphics or long strings until there is no horizontal scrollbar.
  2. Check that the style sheets are displaying your text correctly. Since the style sheets use sans serif fonts, the best way to check is to set your browser's default font to a serif font such as Times New Roman. You'll be able to tell at a glance if your file is not using the style sheets, because your text will not appear in a sans serif font. To fix this problem, check that the style sheet tag at the top of your file is correct.
  3. Check for any other errors in font display or formatting. Often a minor problem with a close tag causes half the file to be displayed in boldface. This is easy to check by viewing your system in NetHelp. You can also check for this by loading the file in Navigator, going to View Source, and looking for the blinking text that indicates unresolved tags. Be sure to fix all display and formatting errors before your final handoff.
  4. Check that all your graphics display properly. If they don't, then the reference to your graphic doesn't match. If the graphic displays but doesn't look right, then you'll need to reproduce it or otherwise fix it.
  5. Check your internal and external links by clicking on each one. If they don't work, then there's a problem in your link that you need to fix. Note that all HREFs within your NetHelp system must be nethelp:urls, or must use the target="_blank" attribute as explained in the Authoring section.
  6. Check all of your table of contents entries by opening each subsection and clicking on each topic name. Each entry should display the correct topic in the Topic Pane.
  7. Check all of your index entries by clicking on every entry, then on each topic name that appears in the Topic Pane. Each index entry should display one or more topic titles in the topic window, and clicking on each topic title should display that topic in the Topic Pane.

Testing Context-Sensitive NetHelp Calls

Currently, we offer two quick methods for testing your NetHelp system without having to worry about hooking it up to your main application. These tests are most helpful for testing context-sensitive calls from the main application, but are also useful in a variety of other situations.

Guide to Known Problems and Solutions

Problem Possible Cause Fixes
You enter a NetHelp URL into the browser Location field and press Enter, but no help topic loads or you get the error message "Unable to load requested topic." The topic is not defined appropriately in the topic file. Look in the topic file to make sure that the topic is anchored appropriately. Then look in the project file and make sure the topic ID was generated appropriately.
Graphics don't appear. Graphic is not a recognizable format or is not in the appropriate location. View the graphic's properties and make sure that...

...the graphic's reference uses legal HTML syntax

...the image is a .GIF or .JPG file

...the graphic is located in the referenced location

Horizontal scrollbar appears. Graphic or nonwrapping text does not fit into default window size. Scale graphics or reduce font size until content fits into window with no scroll bar.
Long sections of text are not formatted properly. Formatting tags have not been properly terminated.

Style sheets are not working correctly.
In the topic file, look at each formatting tag such as <H1>, <H2>, <FONT>, and so on. Make sure each formatting tag has a corresponding end-formatting tag.

Inspect style sheets (if you're using them) to make sure you're using legal HTML.
Clicking on a link displays the error message "Unable to load requested topic." Link uses illegal HREF.

Topic ID is not properly defined.
View the HREF source and make sure it uses legal HTML and points to the appropriate location.

Look in the project file to make sure that the topic has a legal topic ID and uses the NetHelp URL.
Clicking on a link in a topic displays the wrong topic. HREF points to the wrong location. View the HREF source and make sure it uses legal HTML and points to the appropriate location.
Clicking on a Table of Contents entry displays the error message: Failed Assertion. There is a problem with the automatically generated TOC data file. Look in CntData.js for inappropriately generated data. Make sure that data is generated only once, and that code for beginning and ending TOC sections is the same as that in the sample CntData.js file.
Clicking on a Table of Contents entry displays the wrong topic. Wrong anchor name specified in topic heading. View the source for the topic file, and make sure the anchor name is the same one defined in the project file. You may have forgotten to re-run the Builder after changing or adding new TOC anchors.
Clicking on an index keyword displays the error message "Failed Assertion." There is a problem with the automatically generated Index data file. Look in IdxData.js for inappropriately generated data. Make sure that data is generated only once, and that code for beginning and ending sections is the same as that in the sample IdxData.js file.

Problems of this nature can be caused by improperly terminated tags in the topic file, or by duplicate anchor names in the same file. Resolve the tags and anchor names, and then re-generate your index.

Delivering Your NetHelp System

After you've tested your NetHelp system, you're ready to prepare it for installation on your user's computer. All that needs to be done is to copy the entire contents of your help's installed directory to a same-named directory in the same location on your user's computer. This location is always in the NetHelp directory, so your users must have Communicator installed before installing your NetHelp files.

For example, if your NetHelp directory is named YourHelp, you must package the \YourHelp directory and all of its files, including all the section subdirectories and their contents. Your user then installs the \YourHelp directory (and all files and subdirectories in it) into their own ..Communicator\Program\NetHelp\ directory.

There are several methods you can use to package these files for delivery. Often, the combined size of the files is small enough to be packaged on a diskette or made available on a web server for users to download and install.

One easy way to prepare these files is by zipping them up with a zip product, making sure to use the option to include all subdirectories and their contents. Then your user has only to copy the zip file (from diskette or a web site) to the ..Communicator\Program\NetHelp\  directory and unzip it. Similar functionality is available for cross platform use with .jar files; see this site for more information.

Another option for packaging your NetHelp files is to use a commercial installation system such as InstallShield (which is a windows-only solution).