Getting Started with NetHelp2
Excerpted from the NetHelp2 Authoring Guide help system.
Welcome
to NetHelp
NetHelp is an open
standard for viewing HTML-based online help. NetHelp allows you to provide
context-sensitive online help for an application--in any environment--where
Netscape Navigator is present.
NetHelp enables
you to:
-
Provide context-sensitive
help for HTML-based intranet and Web applications
-
Author and maintain
single source files for your help system
-
Use Netscape's
HTML extensions and Plug-ins to provide rich, engaging content
Authoring
for NetHelp
HTML is fast becoming
a standard for network-based information display. Netscape Help therefore
benefits from the new tools available for producing content in HTML. The
same tools and techniques used to publish information to web sites can
be used to construct NetHelp systems. These traditional features, combined
with the NetHelp Builder, will enable you to author and produce powerful
help systems.
-
You can code for
NetHelp with Netscape Composer or your choice of HTML editors.
-
For functionality
beyond HTML, you can use JavaScript functions embedded within HTML pages,
like you'd use WinHelp macros or Guide Script.
-
You can create
your own interface, or adapt the existing NetHelp look and feel to your
own help system.
-
Finally, you can
use the NetHelp Builder to create a Table of Contents and keyword Index
with incremental search capabilities, and present your help system in the
NetHelp browser.
Who
Should Read This Guide
You should read
this guide if you want to build a complete HTML help system like the one
found in Netscape Communicator 4.01. This document is aimed toward three
types of authors:
-
Those who only
need to edit text in existing NetHelp files.
-
Those who need
to add new topics, or change the names of existing topics.
-
Those who need
to create entirely new sections or help systems.
You'll find this
guide useful if you're a technical writer or help content provider. It
will be helpful for you to be familiar with HTML, and to have some experience
with online help systems.
What
This Guide Covers
This guide presents
an overview of NetHelp 2.0 and describes how to author content for a NetHelp
2.0 help system. It illustrates all the steps you will take to create,
test, and deliver a help system, guides you through troubleshooting, and
answers some frequently asked questions.
-
Getting Started
give you an overview of the authoring process for NetHelp, defines NetHelp
2.0 system terminology, explains the role of the NetHelp Builder, and describes
the files you will be working with and ways you can customize your help
system.
-
Authoring explains
how to prepare your computer, and illustrates how to create or convert
your topic files and links.
-
Building shows
you how to install the NetHelp Builder and process your help files, explains
how to test and troubleshoot, answers frequently asked questions, and supports
your delivery of an outstanding help system.
Building
a NetHelp System
Whether you are
starting fresh or converting an existing help system, the process of building
a NetHelp system falls into three phases:
-
involves understanding
the NetHelp system structure
-
learning NetHelp
terminology
-
planning the structure
of your help system
-
involves preparing
your work space
-
writing the topics
of your help system
-
adding links (or
converting) to NetHelp links
-
creating (or converting)
Table of Contents and Index entries
-
may also involve
creating a customized user interface
-
involves installing
and running the NetHelp Builder
-
testing your system
-
revising and troubleshooting
-
delivering the
help system to your audience
Parts
of a NetHelp System
Before you begin,
it will be helpful to understand the parts that constitute a NetHelp system.
This platform
structure depicts how your help topics are viewed through a user interface,
which is supported by NetHelp's platform, which is supported by Communicator's
platform.
Authorable Help
Topics
As an author, you
will focus your efforts on providing a body of instructional information
for your users. You may choose to create graphics to support your text;
you might even include animation and sound in your help topics. Your role
as an author also involves tagging elements in your help topics, just like
you would in HTML, but including NetHelp's unique tags for the Table of
Contents and Index.
Configurable User
Interface
Your end users
will access your help topics through a user interface. Netscape Communicator
and NetHelp provide a platform and a basic user interface, but you have
some control over certain parts of that interface. You may create your
own graphics for the header pane of the help window, and replace the action
buttons in the button bar and locator panes. You may also change the size
of the window and relative sizes of each pane.
NetHelp Platform
NetHelp's JavaScript
and HTML code organize the user interface elements and your unique help
topics. NetHelp builds a Table of Contents and keyword Index for your system.
Communicator Platform
The NetHelp platform
rests on the Communicator platform, allowing you and your end users to
view your help system through Netscape's browser.
You will never
need to touch the Communicator platform, and NetHelp's Builder enables
you to bypass the NetHelp implementation files as well. As an author you
only interact with the top levels of this system structure.
Panes
in a NetHelp Window
The NetHelp window
is divided into areas of navigation and information called panes.
-
The Locator
Pane contains the Table of Contents, Index, and Find functions.
-
The Header Pane
contains graphical information such as the banner and section icons.
-
The Topic Pane
contains the topics, the body of your help information.
-
The Bottom Pane
contains the button bar of action icons and the progress bar.
When you compare
these diagrams, you can see how the parts the the NetHelp system fall into
panes of the NetHelp window.
-
The authorable
content (your topics) falls into the Topic Pane.
-
The configurable
user interface (your banner and section graphics) falls into the Header
Pane.
-
The NetHelp platform
(our user interface and implementation) falls into the Locator Pane and
Bottom Pane.
-
The Communicator
platform supports the entire system.
Directories
in a NetHelp System
Before you begin
building your help system, you should understand the NetHelp directory
structure. All local NetHelp systems live in the NetHelp directory, which
is part of your Communicator installation.
On Mac and UNIX
systems, the NetHelp directory location is relative to where you installed
your Communicator directory.
On PCs the default
location is:
C:\Program
Files\Netscape\Communicator\Program\NetHelp\
Your help system
will live in the NetHelp directory. Within Your Help directory, you will
create subdirectories for each of your sections. The NetHelp implementation
files (graphics files, JavaScript files, and HTML files) must also be located
in Your Help directory.
Each of your
sections will have your HTML topic file, graphics files for the section
Header, an HTML file for the section Header, and the help project file.
Any graphics, animations, or sounds you create to support your help topics
must also reside in this section directory.
Files
in a NetHelp System
Files for your
help system will live on two levels: some files support the implementation
of your help system and live in Your Help directory, while other files
are specific to your help topics and live within your Section directories.
Files in Your Help
Directory
The files that
live in Your Help directory support the implementation of your NetHelp
system. These files are included in the NetHelp template and do not need
to be modified.
There are three
types of implementation files in Your Help directory:
-
Graphics files
are.GIFs that produce the buttons of the NetHelp interface.
-
Structural files
are .HTMs that produce the frameset, styles, and structure of your
NetHelp window.
-
JavaScripts
are .JS files that produce the interactivity of your NetHelp system.
Files in Your Section
Directories
The files that
live in your section directories are specific to your help topics. You
will produce the majority of these files, and then use the NetHelp Builder
to create the project file.
There are four
types of files in your Section directories:
-
The Topic file
is an .HTM file in which you write all of you help topics for that
section.
-
The Header file
is also an .HTM file, and produces your help banner and the interaction
among your sections.
-
The Graphics
files are .GIF files that include your help banner, your section icons,
and any graphics you create to support your help information.
-
The Project
file is an .HPF file that is automatically created for each section
when you run the NetHelp Builder.
Planning
Your NetHelp System
Now that you are
more familiar with the structure of the NetHelp windows, directories, and
files, you'll need to plan your own help system. You begin by structuring
your help content.
Sections
You will divide
your help system into "chunks" of related information called sections,
which show up in the Header pane. In a large help system, sections may
be used to organize a suite of products. Netscape Communicator's help is
divided into sections by product: Navigator, Messenger, Composer, etc.
For a smaller help system, sections may be used to organize information
like the parts in a book. This NetHelp Authoring Guide is divided into
sections by the process of building a help system: Getting Started, Authoring,
and Building.
Subsections
Your sections are
divided into subsections, which show up in both the Locator pane and the
Topic pane. These subsections are a way of breaking up the topic information
and providing a way for your users to scan through the help information.
In the Locator pane the subsections work like folders, expanding and contracting
to reveal their topics.
Topics
Each subsection
is further divided into topics. The heading for each topic shows up in
the Locator pane, and the heading and body of information shows up in the
Topic pane.