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.
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:
-
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.
-
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.
-
The working
directory is a staging area in which you develop your topics, create
graphics, and code your Table of Contents and Index entries.
-
The installed directory is where you run and test your NetHelp system, and where
your completed system will be installed on your users' machines. The Builder
automatically creates the installed directory inside your \nethelp directory,
and the installed directory is given the same name as your working 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:
-
Topic file: This is an .HTM file in which you write
all of your help topics for that section. The topic file can have any name,
but must have the .htm extension. See Developing
Topics.
-
Header file: This is also an .HTM file, and produces
your help banner and the interaction among your sections. This file must
be named ending in Hdr.htm, and the prefix must have up to the
first five characters of your topic file's name. For example, if your topic
file is named build.htm, then the header file for this section
must be named buildHdr.htm. See Customizing
Your Header Pane.
-
Graphics files: These are .GIF files that produce
your help banner and section icons. Any graphics you create to support
your help information must live in this directory as well. See Customizing
Your Header Pane.
-
Project file: This is an .HPF file that is automatically
created for each section when you run the NetHelp Builder. The project
file for each section will always be named help.hpf, and you won't
need to work with this file. See Running
the NetHelp Builder.
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:
-
"Plain" ASCII text editors such as notepad, BBedit, or vi will work fine.
-
If you use Microsoft Word, take care to save your HTML files in text format.
-
Currently, avoid using WordPad, which truncates spaces in ways that the
parser in our data generation tool does not expect.
-
Currently, avoid commercial HTML editors such as HotMetal Pro, HotTamale,
MS Internet Assistant, or MS Front Page. Many of these tools parse and
write HTML in slightly different ways, some of which may not work well
with NetHelp. As we test more tools, we will post results on the
NetHelp SDK web page.
Writing
or Converting Topics
When creating your topic files, keep the following tips in mind:
-
If you are supporting 16-bit Windows, use the "8.3" naming convention,
in other words, your file names must be five characters plus the three-character
"htm" extension. For example, myprj.htm. You are limited
to five-character file names because the final three characters are reserved
for defining the NetHelp header files. For example, if your file name is
myprj.htm, the NetHelp header file will be named myprjHdr.htm.
-
In the HEAD tags of each of your HTML topic files, add the following
text:
<SCRIPT SRC = "../../topic.js" LANGUAGE = "JavaScript1.2"></SCRIPT>
-
Use the <BODY> and </BODY> tags to define the beginning
and ending of your document's body.
-
Do not use an ONLOAD attribute with the BODY tag.
-
Use anchors for all topics.
-
Do not use extraneous white space between characters. For example:
Right |
target=TopicFrame |
Wrong |
target = TopicFrame |
-
Do NOT use any <FONT>, <TEXT>, or <BODY> attributes
on headings or normal topic text. They can corrupt NetHelp's style sheet
entries.
-
Do NOT use the INDEXSTRING attribute in <H1>s. It
is unnecessary, and using it may cause index problems.
-
Be careful when using the <PRE> tag for formatted lines, as
this will cause long lines that are unable to wrap. Consequently, the browser
will use a horizontal scrollbar on the topic window, which looks awkward
and forces the user to either scroll horizontally or adjust the NetHelp
window. You should decide early in your project if this is acceptable,
and make your PRE formatting choices accordingly. See also Using
Graphics and Other HTML Features.
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:
<A NAME="topic_name">Topic Name</A>
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:
nethelp:system/section:topic
Let's take a look at what each of these pieces means:
-
nethelp tells your browser to display the information in a NetHelp
window.
-
system is a string representing your NetHelp system's manufacturer.
It is not case-sensitive. For example:
nethelp:netscape ...
nethelp:AuthGuid ...
nethelp:YourHelp ...
-
section is the directory name of the help section. The section name
is not case-sensitive. For example:
nethelp:netscape/navigator
points to a topic in the Navigator section of the Netscape help
nethelp:AuthGuid/build
points to a topic in the Building section of the Authoring Guide
nethelp:YourHelp/CustServ
points to a topic in the Customer Service section of YourHelp system
-
topic is the ID of your topic. It is not case-sensitive. For example:
nethelp:netscape/navigator:getting_started
points to the Getting Started topic in the navigator section of the netscape help
nethelp:AuthGuid/build:Installing_the_NetHelp_Builder
points to the Installing the NetHelp Builder topic in the Building section of the Authoring Guide
nethelp:YourHelp/CustServ:Responding_to_Inquiries
points to the Responding to Inquiries topic in the Customer Service section of Your Help system
Now let's look at an example of using the nethelp:URL to mark
up a link:
For more information on panes in a NetHelp window, see the
<a href="nethelp:AuthGuid/start:Panes_in_a_NetHelp_Window">NetHelp
Window</a> topic.
generates this link:
For more information on panes in a NetHelp window, see the NetHelp
Window topic.
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:
<A HREF="http://www.anysite.com/anypage.html" target="_blank">Link
to Anypage</A>
The attribute target="_blank" tells the browser to open this
link in a new browser window. If you don't use the TARGET="_blank"
attribute, the new page will be loaded into the topic frame of the NetHelp
window. Since this new content was probably not marked up specifically
for the NetHelp browser, the content will be too large for the NetHelp
window. To avoid confusing your readers, we recommend targeting a new browser
window for such links.
Here is an example of this kind of link:
Here's a link to<A HREF="http://home.netscape.com" target="_blank">Netscape's
site</A> on the World Wide Web.
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:
-
Customize
Your Header Pane: Customize your section elements in the
header pane. These can be text, as in most of the Templates, or graphics,
as in this Authoring Guide and as in Communicator's help system, and in
some of the other Templates.
-
Create
Table of Content entries: Create table of contents entries in each
section to identify subsections and topics for the NetHelp Builder.
-
Create Index entries:
Create the keyword index entries for each topic so the Builder includes
them in the Index.
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:
-
Subsection headings are displayed in bold in the Locator Pane. These
headings do not have topics of their own; rather, they are containers to
organize multiple topics. When a user clicks on a subsection heading in
the Locator Pane, its topic names are displayed (expanded) below it. Clicking
again on the subsection heading closes (collapses) the topics below it.
You code your subsection headings by using <H1> tags
within your content.
-
Topic names are displayed in plain type in the Locator Pane. Clicking
on a topic in the Locator pane displays that topic in the Topic pane. You
code your topic headings by using <H2> tags in your content.
Topics with a heading tag above H2 (H3, H4, and so on) will appear in the
Topic Pane, but not in the Table of Contents.
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:
-
<H1> tags are reserved for coding subsections. Don't use <H1>
tags for any other purpose.
-
<H2> tags are reserved for coding topic names. In other words,
any <H2> tags you mark in your source will appear in 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:
<H1><A NAME="" TOCSTRING="subsection"></A></H1>
What you put in TOCSTRING="subsection" is what will appear in
the Table of Contents. For example:
<H1><A NAME="" TOCSTRING="Basics of a NetHelp System"></A></H1>
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:
-
The NetHelp Builder will find an <H1> tag and contain all <H2>
tags below it until it encounters another <H1> tag.
-
Leave the A NAME definition blank, and do not put text between
the <A> and </A> tags. This maintains the relationship
we have established between the Locator Pane and the Topic Pane.
-
For optimum readability in the narrow Locator Pane, use the shortest possible
string for the TOCSTRING attribute.
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:
<H2><A NAME="anchor_name" TOCSTRING="Topic Name">Topic Name</A></H2>
Here's an example:
<H2><A NAME="Installing_the_NetHelp_Builder" TOCSTRING="Installing">Installing
the NetHelp Builder</A></H2>
Keep these important points in mind when coding topics:
-
Since <H1> tags are reserved for subsection names, topics must
be <H2> tags. Any topics that include text tagged with <H3>,
<H4>, and so on will appear in help topics but will not appear
in the Table of Contents.
-
Make sure your TOCSTRING entry is within the <A NAME>
tag.
-
Do not use extra return characters.
-
For optimum readability in the narrow Locator pane, use the shortest possible
string for your TOCSTRING.
-
Remember that anything tagged <H2> will be contained within
the nearest preceeding <H1> tag.
-
If you don't want a heading to appear in the Table of Contents, simply
don't add a TOCSTRING to your anchor tag.
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:
<H#><A NAME="anchor_name" INDEXSTRING="keyword 1^keyword
2^keyword 3">Heading</A></H#>
For example:
<H2><A NAME="NetHelp_Directories" TOCSTRING="Directories"
INDEXSTRING="directory^directories^file structure^installed directory^working
directory">NetHelp Directories</A></H2>
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:
-
Make sure your INDEXSTRING entry is within the <A NAME>
tag.
-
Do not use INDEXSTRING in <H1> tags.
-
For optimum readability in the narrow Locator pane, use the shortest possible
name for your INDEXSTRING.
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 |