Last updated: 21 February 1997.
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 |
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.
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.
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.
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:
- Java
- Java Applet
- Java Application
- Java Articles
- Java Notes
- etc.
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.
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.
No. HelpIndex is server and browser independent Java program, and so poses no security risk to either the user or your server.
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.
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.
A full HelpIndex licence currently costs £50 per computer. See our purchasing instructions for details.
Yes please, once your 30 day free evaluation trial is up.
The main benefit is that you get a licence to run HelpIndex for a year.
And the full version has no capacity limits.
Just one, although you can keep a local working copy of the site and a further backup copy.
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.
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.
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.
The help index file is not kept up to date automatically.
You must update it yourself, and remember to load it onto your server.
![]()
"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".
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".
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".
Any server will do, as far as we know.
Yes, just open the web page with it in as a local file.
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.
Mainly by exhaustively using it ourselves.
However, we have only tested it under Windows with Netscape Navigator or Microsoft Internet Explorer.
PHD Computer Consultants Ltd.
By paying you get a licence to use HelpIndex.
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.
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.
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.
Och... just read our Getting Started instructions.
The full evaluation development kit is a zip file of about 145kB, expanding to 360kB+.
Och... just read our instructions.
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".
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.
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.
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.
- All the HelpIndex class files (the ones with filenames that end in ".class"), ie HelpIndex.class etc. Except that you do not need the MakeHelpIndex class files, ie MakeHelpIndex.class, ParseHTML.class, HTMLuser.class and ParseURL.class.
- helpindex.gif and hitabs.gif.
- your index file, eg site.hi
- any language files that you are using, eg french.hil
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.
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.
Yes. No special server is needed. And HelpIndex can run without a server, ie you can use the browser to open the HelpIndex pages.
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.
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.
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.
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 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.
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.
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.
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.
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.
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.
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.
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.
Yes, if you must, using a plain text editor. Do not save it in your word processor's own format.
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.
- The most common reason to edit the help index file is to add a type 3 record (Base URL) to make the index file always reference your pages.
- Alternatively you might want to delete the Base URL record if you just want your index to be relative.
- You might want to delete duplicate index records
- You may wish to edit entries or add new entries
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
Yes
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.
There is a language file format defined for HelpIndex version 1, and a separate format defined for version 2.
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.
English
You do not need to specify a language file to use English.
You can copy and use these language files:
Version 1 French french.hil German german.hil Version 2 French french2.hil German german2.hil
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.
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.
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.
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.
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.
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.
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.
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.