Authoring for NetHelp

Now that you have read the Getting Started section and are familiar with the basics of NetHelp, you are ready to begin creating your own NetHelp system.

In this authoring phase you will:

The NetHelp Directory

All local NetHelp systems live in your NetHelp directory, which is already part of your Communicator installation. Your new NetHelp system will also live in this NetHelp directory. Each NetHelp system includes its own set of implementation files, and subdirectories for each of its sections.  Read  Planning your NetHelp System for more information on NetHelp system structure.
Implementation Files and Section Directories

The NetHelp directory is always located in the Communicator directory.

On PCs, the default for this is

C:\Program Files\Netscape\Communicator\Program\NetHelp\

On Macintosh and Unix systems, the location is relative to your Communicator installation.

The Working Directory Versus the Installed Directory

When you are creating a NetHelp system, it is good practice to keep your developmental files in an area separate from the NetHelp Directory. There are a couple of reasons for this separaration:
  1. You can develop content in the location of your choice. The NetHelp directory lives deep within the Communicator directory structure and is inconvenient for developing your help content.
  2. You will minimize the possibility of accidentally making changes to NetHelp systems that already exist within your NetHelp directory, like Communicator's help or this Authoring Guide.
To avoid complications during your authoring process, you need to create a working directory for your NetHelp system.

Working versus Installed Directory

Creating the Working Directory

Create a working directory for editing your NetHelp source files. We recommend that you create your working directory at the root of a drive, such as c:\YourHelp. Since your installed directory will be deep in the Communicator directory structure, the key is to create your working directory in the most convenient location.

Since the working directory's name is used by the Builder to create the installed directory, we recommend that you give the working directory a name that reflects your product. In our examples in this Authoring Guide, we have called it "YourHelp."

At any time during your authoring process, you will be able to run the NetHelp Builder to build your entire NetHelp system. As a part of its building process, the Builder creates the installed directory and copies your NetHelp system to it, where you can then test and use your system.

Using a NetHelp 2.0 Template

NetHelp 2.0 Templates are tiny, but complete "boilerplate" NetHelp systems that we make available in our Template Page. The templates provide placeholder directories and header files for a one section, three-section, or six-section NetHelp system in a narrow, wide, or full screen window.

Once a template is installed in your working directory, you can add or remove section directories, rename the template source files, and start editing the template's HTML files to create your own NetHelp system.

To install a NetHelp 2.0 template, copy the archive for that template to your working directory, and then expand or unzip the archive. The template will expand the NetHelp implementation files and organize the three placeholder section directories and their contents. See our Template Page for more information on currently-available templates.

Setting up Your Section Directories

Whether you use a NetHelp 2.0 Template or not, you need to understand what is involved in setting up your section directories.

Each section in your NetHelp system requires its own directory and related files, as detailed in Directories in a NetHelp System. Use the three sections created by the template: if you need fewer sections, delete one or more of the directories. If you need more sections, create new directories and add the required files as shown here. Whether you add or remove sections from the template, you should rename each section directory to suit your actual sections.

Note that you only have to create and customize your section directories in your working directory. You don't have to do this again in your installed directory because the NetHelp Builder automatically copies your section directories and their contents to your installed directory for you.

Once your section directories are created, you'll populate each of them with four types of files:

Using Composer and Other HTML Editors

You provide your actual help content by creating one HTML file for each section of your NetHelp system. We recommend Netscape Composer for NetHelp authoring. We want you to be comfortable as you write your help topics, so feel free to use an HTML editor of your choice. Keep in mind that we are creating new Java-based plug-ins for Composer that are specifically designed for help authoring, a good reason to start using Composer now. These plug-ins will be available on the NetHelp SDK page along with more tips for using Composer to author your NetHelp system.

If you plan to use an HTML editor other than Composer, keep these tips in mind:

Writing or Converting Topics

When creating your topic files, keep the following tips in mind:

Using Graphics and Other HTML Features

You can add graphics to your content files just as in any HTML document. However, graphics wider than about 340 pixels (280 pixels if you're using one of the narrow Templates) will cause a horizontal scrollbar to appear at the bottom of the topic frame. You should decide early in your project if this is acceptable, and make your graphics choices accordingly.

Except in very few instances as noted in this section, NetHelp places no restrictions on HTML content itself. Anything you can code in HTML 3.2 (or the additional extensions supported in Communicator) can be used in NetHelp help systems--animated gifs, JavaScript or Java code, features requiring plug-ins, and so on--are all possible in NetHelp help systems.

You need to be aware of the dimensions of your NetHelp window and implications its size may have on graphic, or animation placement. You should also think carefully about adding features that your users may not be able to use.  For example, if your user's employer specifies that Java enabling must be turned off, then it doesn't make sense to add Java applets to your NetHelp system.  Likewise, if you add a feature that requires a plug-in, especially one that is not free or one that does not work on all platforms, you're placing a restriction on your help user that may not be reasonable.

Creating Links Within Your NetHelp System

As in any HTML document, you will use anchor tags to define targets for hypertext links in your NetHelp system. Your anchor tags use the familiar syntax: Some anchor tags in your NetHelp system will include additional tag attributes, which will be discussed in Coding for the Table of Contents and Creating Index Keywords.

With a NetHelp system, all links to anchor tags within your NetHelp system will use the nethelp:URL. You can still use mailto and javascript links, as well as the http protocol  just as you would in any HTML content. See Creating Links Beyond Your NetHelp System for more details.

To create a link to a NetHelp topic you must specify the destination topic using the nethelp:URL. The nethelp:URL uses this syntax:

Let's take a look at what each of these pieces means: Now let's look at an example of using the nethelp:URL to mark up a link: generates this link: Note that these nethelp:URL links only work if you are viewing your files with Communicator (Communicator is currently the only browser that understands the nethelp:URL).

Keep in mind that the following topic IDs are reserved by NetHelp and cannot be used as topic IDs: TOC, Search, Index, First, Last, Browse-Forward, Browse-Backward.

Creating Links Beyond Your NetHelp System

In your NetHelp topic files, you can also add links to pages outside of your NetHelp system.

You can use the TARGET attribute of the anchor tag to link to any page by using the following syntax:

Here is an example of this kind of link: generates the line: NetHelp 2.0 has integrated two methods of calling secondary windows, but this will not be detailed until a later document.

A Quick Overview

Creating the remaining navigation elements of your NetHelp system is easy once you've decided how many sections you'll use and have set up your section directories.  There are three remaining steps before you run the NetHelp Builder: It is also possible to customize some of the navigation graphics, such as the Locator buttons, or the back and forward buttons. This will be explained in a future document.

Customizing Your Header Pane

Whether you're using one of our templates or creating your sections and header elements from scratch, you'll need to customize your Header Pane for your NetHelp system. You can make your Header Pane with simple text, or you can create graphics.

Using Text to Create Your Header Pane

In the plain text template, the header uses a table to organize the NetHelp system title and sections. You should look at the markup for this table as you read the following explanation.

The first table row produces the title of your NetHelp system. Take care not to make the font size too large, as it will cause your title to wrap and, consequently, force your sections out of the Header pane.

The second table row produces the section selectors for your NetHelp system. Our Authoring Guide has three sections, so we used three cells.

Notice that in the first table row, the <TD COLSPAN=3> tag is set to span across the three cells that contain our sections. If your NetHelp system has five sections, your first row will be <TD COLSPAN=5> and your second row should include five cells for your sections.

We have used colors to highlight which section the user is currently in. Our active section is highlighted in yellow, while our other available sections are beige.

Notice that the available sections each have an anchor tag that links to its respective section.

The Header table follows a simple pattern that you can use to delete or add sections for your own NetHelp system. The pattern is as follows:

For Section A
    Table Row 1:
        Cell 1: Title of Your Help System
        Cell 2: nbsp;
        Cell 3: nbsp;
    Table Row 2:
        Cell 1: Section A in highlight color
        Cell 2: Section B in available color with link to Section B
        Cell 3: Section C in available color with link to Section C

For Section B
        Table Row 1:
        Cell 1: Title of Your Help System
        Cell 2: nbsp;
        Cell 3: nbsp;
    Table Row 2:
        Cell 1: Section A in available color with link to Section A
        Cell 2: Section B in highlight color
        Cell 3: Section C in available color with link to Section C

For Section C
    Table Row 1:
        Cell 1: Title of Your Help System
        Cell 2: nbsp;
        Cell 3: nbsp;
    Table Row 2:
        Cell 1: Section A in available color with link to Section A
        Cell 2: Section B in available color with link to Section B
        Cell 3: Section C in highlight color

Using Graphics to Create Your Header Pane

You may decide to use graphics (as we have) to create a button-like interface for moving between sections.  You are welcome to edit and use the graphics we provided for this NetHelp system, or replace them with your own graphics files. Take a look at our Authoring Guide Header code as you read the following information:

For a Header Pane created with graphics, you do not need to use a table. Instead, place your help system title banner followed by a <BR> tag. Then place your section graphics and appropriate links. Take care not to use any <BR> or hard returns between your section graphics, as this may cause an unpredictable appearance in the Header Pane.

We recommend that you name your graphics files with relevant names. For example, our banner is "banner.gif", an available section is "SectionA.gif", and our current, or highlighted section is "SectionA_sel.gif".

To create the links, use the pattern described in the Simple Text Header example. 

How the Table of Contents Works

Before reading this section you should read Planning Your NetHelp System.

The Table of Contents is displayed in the Locator Pane. Clicking the "Contents" button displays the Table of Contents for the current section.

The Table of Contents has two types of entries:

The diagrams in Planning Your NetHelp system will clarify the structure of your help content and how it relates to the NetHelp window.

Table of Contents entries are made with NetHelp's new TOCSTRING attribute of the <A> tag. The TOCSTRING tag tells the NetHelp Builder what to display in the Locator pane's Table of Contents. This new <A> tag attribute makes it possible for you to use a shorter heading name in your Table of Contents. A shorter string displays better in the Locator pane, and increases readability for the user.

Keep these important facts in mind when coding the Table of Contents:

Coding a Subsection for the Table of Contents

To code a subsection name, use an <H1> tag, and add an <A> tag with a TOCSTRING attribute. For example: What you put in TOCSTRING="subsection" is what will appear in the Table of Contents. For example: Notice that the A NAME="" definition is left blank, and there is no text within the <A> tags. This is because your <H1> tags do not appear in your Topic Pane; they only appear in the Table of Contents in your Locator Pane. By leaving the A NAME definition blank, you cannot accidentally link to a subsection heading.

Keep these important points in mind when coding subsections:

Coding a Topic for the Table of Contents

To code a Table of Contents entry for a topic, use the TOCSTRING tag with the following format: Here's an example: Keep these important points in mind when coding topics:

How the Index Works

The Index is displayed in the Locator Pane. Clicking the Index button displays a list of keywords. When you click a keyword, the Topic Pane displays links to all of the the topics associated with that keyword. When you click one of the displayed links, that topic appears in the Topic Pane.

Your users can also do an incremental search on keywords by typing into the "Look for:" field. As each character is typed, NetHelp searches for and displays keywords as they match.

Creating Index Keywords

To code index keywords for a topic, use an INDEXSTRING attribute in the <A> tag. Enter the keywords using the following syntax: For example: In this example, the keywords "directory", "directories", "file structure", "installed directory" and "working directory" have been added to the the anchor tag for a topic named "NetHelp Directories."  When users click the keywords "directory", "directories", "file structure", "installed directory" and "working directory" in the index, a link to the topic name "NetHelp Directories" is displayed in the topic pane (perhaps with other entries that share the same keywords, such as "Planning Your NetHelp System" or "Preparing Your Workspace"). The user can then click on the link "NetHelp Directories" and the full topic will appear.

Keep these important facts in mind when coding index keywords:

After you've coded the Table of Contents entries and Index entries, you will run the NetHelp Builder. The Builder parses the content files, and copies the table of contents entries to a special JavaScript file, CntData.js. and copies the keyword entries to a special JavaScript file, IdxData.js. When you run your NetHelp system, NetHelp uses the information in these JavaScript files. 

NetHelp Files

This table contains fairly technical descriptions of most of the files in the root directory of the NetHelp 2.0 implementation. Files contained in section directories are described in Files in a NetHelp System. It is not necessary for you to understand this material in order to author NetHelp 2.0 systems; we provide this as a reference for those who wish to understand more about NetHelp 2.0.
File Contents Used By
Header Pane
Header.js Attaches events in the Header pane to event handlers in System.js. Included in the header file for each section (xxxxxHdr.htm).
Topic Pane
Topic.js Attaches events in the Topic pane to event handlers in System.js. Included in every content file.
Button Bar
Back_*.gif Back button (4 states) NavUI.htm
Button.js Code for button objects and the button bar.  Used in NavUI.htm. NavUI.htm and ToolUI.htm
Exit_*.gif Exit button (4 states) NavUI.htm
Forw_*.gif Forward button (4 states) NavUI.htm
NavUI.htm Document filling one frame in the button bar. Creates the Forward, Backward, Print, and Exit buttons. System.js
Prnt_*.gif Print button (4 states) NavUI.htm
Status.htm Document filling one frame in the button bar. Displays the status bar and includes code for changing the status bar. The status bar is the animated gif that indicates when NetHelp is loading TOC or index information. It appears in the left end of the button bar. System.js
Wait.gif Animated GIF for progress bar. Status.htm
Locator Pane
CntData.js Initializes a JavaScript array with data for each section's table of contents. (Generated by the Builder tool.) CntTool.htm
CntTool.js Code to create and manage the Table of Contents display. CntTool.htm
CntTool.htm Page for the Locator Pane when the table of contents is displayed. Loads JavaScript and defines frames. System.js and ToolUI.htm
IdxFill.htm Page with input box and and JavaScript implementation for incremental search in the index.  IdxTool.htm
IdxData.js Initializes a JavaScript array with data for each section's index. (Generated by the Builder tool.) IdxTool.htm
IdxKey.htm The document where index entries matching the user's search criteria are displayed. IdxFill.htm
IdxTool.htm Document displayed when user clicks the Index button. Loads JavaScript and defines frames for IdxFill.htm and IdxKey.htm. System.js and ToolUI.htm
IdxTopic.htm Document displaying all the index entries for the current section.  Each entry is a link.  IdxKey.htm
System.htm Loads the core JavaScript files. NSHIfrm.htm creates an invisible frame to hold this document. NSHIfrm.htm
ToolUI.htm Document displaying the Contents, Index, and Find buttons. System.js
Tool_*.gif Image used for Contents, Index, and Find buttons. (3 states) ToolUI.htm
General System
Blank.htm An empty HTML skeleton used to fill frames where NetHelp will later display help tools or contents. CntTool.htm and NSHIfrm.htm
Local-1.js Sets many user interface strings for the Help system. Useful for localization. System.htm
NoJSerr.htm Blank document displayed in the Topic Pane while help loads. Warns the user if JavaScript is not enabled. NSHIfrm.htm
NSHIfrm.htm The primary NetHelp user interface file. Defines the frame set dividing the NetHelp window into panes. Loads the System.js code. Named in each project file (help.hpf) and loaded by the browser.
Stack.js Defines a simple stack class in JavaScript. Used in System.js to maintain a history list for the Forward and Back buttons. System.js
System.js The primary NetHelp implementation file. Defines a System object with handlers for user interface events such as clicking buttons and links. System.htm
Utility.js Miscellaneous functions for handling URLs and errors. various