Last updated: 21 February 1997.

HelpIndex Frequently Asked Questions (FAQ)

This page is a list of Frequently Asked Questions about the PHD HelpIndex applet. HelpIndex can be found at http://www.phdcc.com/helpindex/

The questions covers HelpIndex basics, support issues and a trouble shooting guide. Please email HelpIndex support if you have a question which is not answered here.

Page Contents
The most Frequent FAQ
Basics 1
Basics 2
HelpIndex Usage
How to put HelpIndex on your page
MakeHelpIndex
Help Index File
Language Files
Advanced Issues
Errors you might get

The most Frequent FAQ

I cannot download the development kit. How can I get it?

You can get the latest full evaluation development kit from our Web site: PHDhi171.zip is about 145kB long.

Email Chris Cant at support@phdcc.com and ask him to send you a copy of the development kit as an attached file. You must be able to accept MIME encoded emails for this to work.

If you get a DNS error or other timeout, please try this hard-wired URL to the HelpIndex site.


Basics 1

What does HelpIndex do?

HelpIndex provides a contents tree and keyword search facility for a web site.

Like other help systems, there is a Contents tree of the pages on a site. In the Index you can type in the first few letters of the word you are looking for; any matching indices are displayed. Select the Display Page button to show the page in the target frame.

Different contents/index sets can be chosen in the Select tab.

HelpIndex may either run within a web page or as a floating window above the browser.

HelpIndex is browser and server independent as it uses static help index files. The companion MakeHelpIndex Java application may be used to build the help index files. Available soon: HelpIndex Workshop is a Windows program to build and edit help index files.

HelpIndex is better than a server based text search as you can configure the keywords precisely. It can be easier and cheaper than setting up such a server based search.

You may evaluate the index-only and capacity-limited version 1.7.1 for 30 days.

Full HelpIndex documentation and examples of its use can be found at: http://www.phdcc.com/helpindex/

Any queries about HelpIndex should be directed to Chris Cant.

Why should I use HelpIndex?

HelpIndex lets users find the pages on your site easily. They simply look through the contents, or type in the word that they want to look up.

With some imagination, you can use HelpIndex for other purposes, eg a user database.

Don't server text searches do the same as HelpIndex's Index?

They do a similar job, but HelpIndex is much better...

A text search indiscriminately finds any word wherever it appears in any page on the server. For example doing a text search for Java at the PHD site, brought up over 200 references, listing each web page, starting with those with the highest number of hits.

In contrast, using HelpIndex should be easier and give better results. Simply typing in J in the index shows a list of all the indices beginning with J. If Java is there, a user can select it right away. More importantly, the index list will show the list of indexes which are definitely there. On the PHD site, typing Java found these indices:

So a user's search for Java can be more targeted, they will see what is definitely there, and be able to pin-point the page they are interested in more quickly.

Another benefit of HelpIndex is that server searches can be complicated or costly to set up with your web space service provider. If you need a new CGI script, then this will have to be vetted to see if it is a security risk. HelpIndex is server and browser independent Java program, and so poses no security risk to either the user or your server.

And, of course, with version 2 you get a contents view as well.

What is a typical usage of HelpIndex?

Most people will use HelpIndex to provide an index to their site. This allows users to search their site quickly for the information they want.

Typically would set up HelpIndex to run as a search form on a page, perhaps as a contents frame in a frameset. Or you can run HelpIndex as a small icon; if the user clicks on the icon, a "floating" HelpIndex window appears above the browser.

You can have more than index for a site, eg in different languages.

Is there a security risk?

No. HelpIndex is server and browser independent Java program, and so poses no security risk to either the user or your server.

What browser do I need?

Any browser that supports Java will do. Make sure that Java is enabled.

On a Windows 95 or NT PC, Netscape Navigator 2.0 or 3.0 and Microsoft Internet Explorer 3.0 will work. We found that Netscape Navigator 3.0 gave the best results.

Where can I get it?

From PHD's HelpIndex web site: http://www.phdcc.com/helpindex. Follow the link to the "Downloading" page. Instructions are given here on how to download the evaluation HelpIndex development kit.

The version that you download is version 1.7.1 for evaluation only and so has capacity limits. Your index file cannot have more than 100 URLs and 500 indices. The full version 2 has no limits.

You have 30 days to try HelpIndex before you must pay for a full licence or delete all the software from your systems.

What does it cost?

A full HelpIndex licence currently costs £50 per computer. See our purchasing instructions for details.

Must I purchase a full licence?

Yes please, once your 30 day free evaluation trial is up.

What do I get when I pay for a full licence?

The main benefit is that you get a licence to run HelpIndex for a year.

And the full version has no capacity limits.

How many sites does a full licence cover?

Just one, although you can keep a local working copy of the site and a further backup copy.

What improvements do you plan?

Version 2 has just been released. Its main improvement is to have a Contents tree view.

The next development is a HelpIndex Workshop. This Windows program has the MakeHelpIndex functionalty but also allows you to edit help index files. It will soon become an essential tool for HelpIndex site designers.

We have lots of other ideas, see our list of possible improvements.


Basics 2

How does HelpIndex work?

When a user visits your site's HelpIndex page, the relevant Java classes are loaded temporarily to their computer.

HelpIndex then reads your "help index file" from your server. It then lets displays the Contents, etc for you to use.

Note very carefully that HelpIndex does not generate its index file for your site automatically. You must create it. The companion program MakeHelpIndex can be used to make a help index file from your existing web pages. You must keep the index file up to date if you change your pages.

How do I make the help index file?

The help index file lists the pages on your site and the keywords which a user can type to search for those pages.

While you can make this index file "by hand" using an ordinary text editor, most people will use the companion program MakeHelpIndex to make the index file automatically from your existing web pages.

How is the help index file kept up to date?

The help index file is not kept up to date automatically.

You must update it yourself, and remember to load it onto your server.

What's icon mode? What's a floating window?

"Icon mode" is where HelpIndex starts up on a user's screen as a small icon, usually the "double question marks" logo shown here.

When the user clicks the icon, a new "floating window" appears above the browser with the search form. You can move it around. Clicking the browser may hide the floating window, but it can still be selected again

You must specify icon mode when you call HelpIndex by setting the mode parameter to "icon".

What's applet mode?

Applet mode is where HelpIndex appears on a web page (rather than in a floating window).

HelpIndex is in applet mode by default, but you can set it explicitly by setting the mode parameter to "applet".

What are the high and wide modes?

The default mode is "high", where the search form is higher than it is wide. In "wide" mode, the index prompts are beside the fields, making the applet shorter and wide. Version 1 defaults to "wide" mode.

Here's an example of "high mode".

Add either "high" or "wide" to the mode parameter, eg "applet high" or "icon wide".

What server do I need to run HelpIndex?

Any server will do, as far as we know.

Can I run HelpIndex locally without a server?

Yes, just open the web page with it in as a local file.

What platform does HelpIndex run on?

It will run on any platform that has a browser which can run Java.

For Windows 95 and NT PCs, most people use either Netscape Navigator 3.0 or Microsoft Internet Explorer 3.0.

HelpIndex should run in other browsers on other platforms, but we have not checked this. There are some minor problems when running from an Apple Macintosh.

To run MakeHelpIndex your computer must have a Java Virtual Machine. This is not provided by a browser. You must download the latest Java Development Kit from Sun and install it. See our Getting Started Guide.

How have you tested HelpIndex?

Mainly by exhaustively using it ourselves.

However, we have only tested it under Windows with Netscape Navigator or Microsoft Internet Explorer.

Who owns HelpIndex?

PHD Computer Consultants Ltd.

By paying you get a licence to use HelpIndex.

Can I get a source code license?

Possibly, provided you are not developing a rival product. In the standard source code package, you just get the source code once. For a higher fee, you can receive the source code for all updates in the coming year.


HelpIndex Usage

How do people use HelpIndex?

People who visit your web site with a Java-enabled browser will see HelpIndex when they go to the page where you have put it. They will either see an icon to click or the applet directly.

Once the help index is loaded, a user can now look through the Contents tree or select the Index and type in a query. See the examples for further instructions.

How long will it take to download?

The HelpIndex classes are about 80kB long. A loading message and HelpIndex icon is displayed as the classes and index file load.

At the very least, these classes will take a few seconds to download, but if you are calling from far away or the lines are congested then it may take some time.

If your users are desperate for faster response times then they can choose to load the HelpIndex classes on their computer permanently. However this is not trivial to set up and they do not automatically use newer versions that you might post. If you are still interested, read these instructions.


How to put HelpIndex on your web page

OK, how do I put HelpIndex on my web page?

Och... just read our Getting Started instructions.

How big is the development kit?

The full evaluation development kit is a zip file of about 145kB, expanding to 360kB+.

What HTML should I use?

Och... just read our instructions.

How do I use icon mode?

Use the following HTML:

<APPLET code=HelpIndex.class width=70 height=80>
<PARAM NAME=index VALUE=siteindex.hi>
<PARAM NAME=mode VALUE="icon wide">
Sorry, you need a browser that runs Java to see the Help Index.
</APPLET>

Note that the applet has the dimensions of the helpindex.gif image, ie 70x80, and the mode parameter is set to "icon wide".

How I use applet mode?

Use the following HTML:

<APPLET code=HelpIndex.class width=450 height=250>
<PARAM NAME=index VALUE=siteindex.hi>
<PARAM NAME=mode VALUE="applet wide">
Sorry, you need a browser that runs Java to see the Help Index.
</APPLET>

Note that the applet is big enough for the "wide" version of the search form.

How do I make the help index file?

The simplest way is to run MakeHelpIndex as described in our Getting Started instructions.

You can build a help index file by hand, but we would not recommend it. However you may wish to tweak the index file that MakeHelpIndex produced.

If your web site changes significantly, remember to update your help index file. If you run MakeHelpIndex again, make sure that you perform any hand edits again. In a future version, we hope to provide a tool which will remember your edits.

How do I keep my index file up to date?

If your web site changes significantly, remember to update your help index file. Usually you will do this by running MakeHelpIndex again.

If you run MakeHelpIndex again, make sure that you perform any hand edits again. Soon we hope to provide a tool which will remember your edits.

What files do I upload to the server?

When you upload files to your server, remember to preserve the case of the file names, eg use file name HelpIndex.class, not helpindex.class. Most modern utility programs preserve case automatically. However, some old versions of WS_FTP for example, did not preserve case.

Does the index only reference my site?

Your index file can reference any web page. For example, the JDK example on PHD's site will display pages on Sun's JavaSoft server.

However, MakeHelpIndex only generates indices for links on one site. So you will have to add off-site links by hand. This might simply be by adding a Base URL record to the index file.

Can I use HelpIndex on my Intranet?

Yes. No special server is needed. And HelpIndex can run without a server, ie you can use the browser to open the HelpIndex pages.

How do I use HelpIndex in frames?

The main technique is to specify the target frame, ie which frame is used when Display Page is pressed.

You can specify a default target using the target applet parameter. Or you can specify a target on a index by index basis by setting the Target field in the relevant Index Item record in the help index file.

The default target frame is _self, ie the selected page replaces the HelpIndex page. _parent specifies the parent frame, _top the top-most frame and _blank a new blank window. Other target names can be given; these should match the names in your frameset.

Here are some suggestions for how to use HelpIndex in frame sets.

How do I display a page in a new browser window?

As explained above, you can set the applet target parameter or the Target field in the relevant Index Item record in the help index file.

How do I make the list boxes wider?

If in applet mode, simply make the APPLET WIDTH bigger.

In icon mode, there is no way of changing the initial size of the floating window, but the user can make it wider simply by resizing the window.

I've changed my help index file, but HelpIndex is still using the old version. What's going wrong?

Have you uploaded the new index file to your server?

Or, your browser may be caching the old version, ie keeping the old version in memory and not bothering to check to see if it has changed. The simplest solution is simply to quit your browser and restart it. This is a pain.

A more drastic solution is to disable caching in your browser, but this will seriously degrade your other web browsing.

This also applies if you change the icon GIF file, or indeed if you change the class files. So if you have just got a later version of HelpIndex you must stop and restart to use the new version.


MakeHelpIndex

What's MakeHelpIndex?

MakeHelpIndex is a program which you can use to build a help index file from your existing web pages.

So it goes through all your web pages automatically and builds an index file from the page titles and anchor names.

Remember that if your web site changes significantly, then you will need to run MakeHelpIndex again to keep the help index up to date.

MakeHelpIndex is a Java application. This means that it does not run from a web page with a browser. You need a Java Virtual Machine on your computer. Read our Getting Started instructions for details of how to get one of these beasts.

We to have a Windows-only version of MakeHelpIndex soon, which will not only be faster, but will also allow index files to edited easily.

Where do I get it? What does it cost?

MakeHelpIndex is a part of the standard HelpIndex development kits. You must pay for a full HelpIndex licence to continue using MakeHelpIndex after 30 days.

There are no capacity limits in the evaluation MakeHelpIndex. MakeHelpIndex will warn you if the generated index file will exceed the evaluation HelpIndex capacity limits.

What do I need to run it?

You need a Java Virtual Machine (JVM) on your computer. This is not provided by web browsers. New operating systems may include a JVM as standard.

The usual way to get a JVM is to download and install Sun JavaSoft's Java Development Kit (JDK). Make sure that you select the right version for your operating system. At the time of writing JDK 1.02 is the latest version available. JDK 1.1 should be available in February 1997.

I understand that an Apple Mac JVM is available at http://www.devtools.apple.com/mrj/text/product/index.html.

Please read our our Getting Started instructions for details of how to get the JDK and install it.

Then follow the usage instructions for details of how to run MakeHelpIndex.

Does MakeHelpIndex index every word in my pages?

No. Not only would this make the index file too big and so unusable.

You can add more indices by hand, or alter your HTML to make sure that MakeHelpIndex generates the required indices automatically.

Where do I get a Java Virtual Machine?

The usual way to get a JVM is to download and install Sun JavaSoft's Java Development Kit (JDK). Make sue that you select the right version for your operating system. At the time of writing JDK 1.02 is the latest version available. JDK 1.1 should be available in February 1997.

I understand that an Apple Mac JVM is available at http://www.devtools.apple.com/mrj/text/product/index.html.


Help Index File

What is the help index file?

The help index file primarily contains the list of indices which you want to appear when people visit your site's HelpIndex page.

When a user visits a page with HelpIndex, first the HelpIndex Java classes are loaded from the server. When HelpIndex starts running, it loads the help index file that you have specified in your index applet parameter. When the index file has been read, HelpIndex can show its list of indices and respond to user input.

The help index file is actually just plain text, with each line a "record". There's one Header record, and then one or more URL, Index Item and Base URL records. Each URL record defines a URL, eg a web page. Each Index Item record defines an index, ie something the user searches for. Finally, one or more Base URL records define a prefix for all following URLs. The format uses short-cuts and the Base URL records to make the index file smaller. For details, please see the Index File Format Specification.

PHD has deemed that help index files usually have a filename extension of .hi, eg site.hi, but you can use whatever name takes your fancy.

How do I make it?

Most people make their help index file using MakeHelpIndex. This analyses your existing web pages and builds a help index file for you automatically.

Check that the index file generated by MakeHelpIndex is what you want. If there are changes then you can simply edit the help index file by hand using a plain text editor. Dare we say it, but an alternative would be to change your HTML so that MakeHelpIndex generates the right index file. This solution is better as it means that you do not have to do edits by hand every time you update your web site and re-run MakeHelpIndex.

So, you can make the help index file by hand if you are a masochist.

Finally, if you are using HelpIndex as a database viewer, then you will want a programmer to generate the index file directly from your real database. Email PHD if you would like our help doing this.

Where do I put it?

Usually you put the index file in the same directory as HelpIndex, and upload it to your server.

If you know what you are doing, you can put it in a different directory. Note that Java security restrictions will limit which directories HelpIndex can access.

Can I edit the help index file by hand?

Yes, if you must, using a plain text editor. Do not save it in your word processor's own format.

Why should I want to edit the help index file?

The help index file might need tidying up after you have created it with MakeHelpIndex. Remember that you should update your help index file after every update to your web pages, so you do not want to be doing a lot of changes every time. Alternatively, you might want to consider altering your web pages so that the right help index file is generated by MakeHelpIndex.

What versions of the help index file are there?

There are three versions, with different Format codes. Format 1.2 has a Format code of 1 and Format sub-code of 2.

Format 0 is the oldest version and is effectively obsolete.

Format 1.2 is the current version, supported by HelpIndex 2.0.

Format 1.1 is recognised by HelpIndex 1.5.x

Can HelpIndex read all old versions of the help index file?

Yes


Language Files

What's a language file?

A language file has a set of strings which HelpIndex uses on its search form as the field and button names, etc.

For example, a version 2 French language file would change the name of the Display Page button to Exposez la page.

Note that changing the language file does not change your index file at all. However you might like to provide, say two separate HelpIndex search forms, one with an English language file and an Engish index file, and the other with a French language file and a French index.

A language file must be in a defined format given in our language file specification.

What versions of a language file are there?

There is a language file format defined for HelpIndex version 1, and a separate format defined for version 2.

How do I use a language file?

In version 2, specify the language with the corresponding index parameter, eg:

<PARAM NAME=index1 VALUE="site.hi,french2.hil">

Or for version 1, you must set the language parameter to the URL of your language file, eg:
<PARAM NAME=language VALUE="french.hil">

Make sure that you upload the language file to your server.

What language does HelpIndex use by default?

English

You do not need to specify a language file to use English.

What language files have you got available?

You can copy and use these language files:

Version 1 French french.hil German german.hil
Version 2 French french2.hil German german2.hil

What else can I use the language file for?

You can also use a language file to change some the prompts if you have a specialised use of HelpIndex. For example our user information database example changes the Indices prompt to Users, etc.

Does using a language file convert my index file into that language?

No, changing the language file does not change your index file at all. However you might like to use English with an Engish index file, and a French language file with a French index. Specify two index parameters in your HTML, eg

<PARAM NAME=index1 VALUE=english.hi>
<PARAM NAME=index2 VALUE=french.hi,french2.hil>

In version 1, you would have to use two separate forms, and the index and language parameters instead.


Advanced Issues

How can I speed up the loading of HelpIndex?

A user could load the HelpIndex classes permanently onto their computer, following our instructions. However this is a rather complicated process and they will not be able to use any new versions of HelpIndex that you put on your site.

Should I alter my HTML?

There is no need to alter your HTML to use HelpIndex.

However, if you use MakeHelpIndex to generate your help index file from your web pages, then you may find that altering your HTML will produced a better index file. For example, you might like to change a page title or introduce keywords.

What's this new KEYWORDS attribute to the A tag?

The KEYWORDS attribute is a new non-standard addition to the HTML A tag. However, using it will not stop your pages from working as browsers will just ignore it.

KEYWORDS is used by MakeHelpIndex to generate more index entries automatically.

MakeHelpIndex will look at this tag
<A NAME=prod>Products</A>
and generate an index entry of "Products" which will point to this page anchor.

Using KEYWORDS, MakeHelpIndex will look at this tag
<A NAME=prod KEYWORDS=Software>Products</A>
and generate two index entries, ie "Products" and "Software", both of which will point to this page anchor.

Can I use the CODEBASE attribute in my APPLET tag?

Yes, but all your class and gif files must be in the directory that you specify.

Remember that your help index file must be accessible to HelpIndex. Java security rules say that it cannot access a directory higher in the disk hierarchy. So if HelpIndex is in a classes sub-directory, then your help index file must be in classes or lower.

Important: Note carefully that the HelpIndex classes must be on the same server as the web page which calls it. If this were allowed then you would be using the resources of someone else's server.

See usage.


Errors you might get

What's this "HelpIndex page must be on same server as applet classes" message?

This message will appear in place of the icon or form if you have set the APPLET CODEBASE to refer to a different server, eg if your web page is on www.you.com but you use CODEBASE to refer to HelpIndex on the PHD server, www.phdcc.com. After this message (if there is room) you will see the name of the CODEBASE host and the name of the HTML host.

HelpIndex does not allow this. You must have the HelpIndex classes on your server. This stops you referring to HelpIndex on PHD's server from your own pages.

ClassFormat error

This usually means that you have not written your HTML to call HelpIndex quite right. You must have exactly the correct capitalisation. Using helpindex.html sometimes results in this ClassFormat error.

<APPLET code=HelpIndex.class width=450 height=250>
<PARAM NAME=index VALUE=site.hi>
</APPLET>

Alternatively, a ClassFormat error means that the Java class files were corrupted somehow.
Make sure that you have got the latest versions of all the classes and make sure that they are uploaded to your server correctly.


HelpIndex    PHD