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:
-
NetHelp is not compiled. Windows help systems and AppleGuide help
systems are compiled: the source files are compressed and changed into
a binary format that is unreadable except in the corresponding help environment.
In NetHelp, your content files are read by the Builder, but
are not modified by it in any way. The Builder uses information it reads
from your content files to create the project files, and the index and
Table of Contents data files.
-
The NetHelp Builder is a Java applet. Like most Java applets, it
runs from within your browser (technically, from within your browser's
Java Virtual Machine, or VM). The user interface for the Builder is an
HTML file to which you simply point your browser. Also, being Java-based
means that you can run the Builder from any OS platform supported by your
browser; in Communicator's case that means you can run the Builder from
Win32 or Win16, from Macintosh, or from UNIX. Other help systems use OS-specific
compilers that are run like regular applications - not from within the
browser.
Installing
the NetHelp Builder
Follow these steps to install the NetHelp Builder:
-
Copy the builder directory from the NetHelp
2.0 SDK to your own machine.
-
Run Communicator and open the builder.htm file from the builder
directory you just copied.
-
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:
-
In Communicator, select the NetHelp Builder bookmark to display the tool.
-
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.
-
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.
-
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.
-
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).
-
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.
-
Leave the NetHelp Version button set to "2.0". The 1.0 setting is for backward
compatibility with earlier NetHelp versions.
-
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:
-
Write and edit your help files in your working directory
-
Run the Builder (which processes your files and moves them to your installed
directory)
-
Test your files from your installed directory.
Make fixes in your help files in your working directory. Repeat this
process until the testing reveals no significant errors.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
You can paste a nethelp:URL directly into Communicator's location
field and then press Enter to display any NetHelp topic in the NetHelp
2.0 window and frameset. If the topic loads correctly, then that nethelp
URL is correct. If the topic doesn't load properly, then something is wrong
in the nethelp:url. See the troubleshooting
section for problems and possible solutions to these errors.
-
Under Windows 95 or NT 4.0, you can also create a Windows shortcut to call
a specific URL. The shortcut can be located on the desktop or in any folder.
One way to do this is to right-click on the desktop, and select New>Shortcut
from the pop-up menu. In the edit field, add the path to wherever you've
installed Navigator, select or enter netscape.exe followed by
a space, followed by nethelp followed by the URL you want to display.
For example, C:\Program Files\Netscape\Communicator\Program\netscape.exe
nethelp:URL. When you run this shortcut, Navigator will run and display
the indicated URL (in a NetHelp window if it's a nethelp: URL).
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).