Keywords for WINS, Version 1.1
by Earl Borah, written for: Chemeketa Online
                            http://bbs.chemek.cc.or.us
                            Offering college courses online since 1990

***FREEWARE!***


CONTENTS:

Filename                      Location             Description
--------                      --------             -----------
*.kwd                         \wc5\keywords\       Sample keyword files
cannot.find.keyword.htm       \wc5\http\           Error message page
invalid.keyword.security.htm  \wc5\http\           Error message page
keyword.list.htm              \wc5\http\template\  Lists available keywords
html-keyword.wcx              \wc5\                Progam file
readme.txt                    anywhere             This documentation



DESCRIPTION:
I was thinking of new (and hopefully easy) ways to navigate our site, and came
up with borrowing the concept of Keywords (or "Go" words) from the online
services and adding them to web pages. This is the result, with a few twists
appropriate for WINS.



WHAT'S NEW:
Version 1.1 fixes a minor bug in the Keyword List routine (technically, it
fixes a bug in Netscape -- the Keyword List routine itself was fine). If you
had a keyword that included a space, and your keyword list was set up to allow
users to click on the name of the keyword to activate it (see the updated
KEYWORD.LIST.HTM file for an example), the list that was generated in version
1.0 would include a space in the link. This caused problems for some versions
of Netscape, which would result in portion of the keyword after the space
being ignored if the user clicked on the link in the web page (so a keyword
like HELP EMAIL would be treated as just HELP). This did not appear to cause
problems in Internet Explorer.

To fix this, version 1.1 uses the SUB3 variable to display the LINK to to the
keyword (by replacing all spaces with + symbols), while the SUB1 variable
continues to show the keyword with the space. See the updated KEYWORD.LIST.HTM
file for an example of this in action.



INSTALLATION:
Unzip the files into the appropriate directories. Since this archive makes use
of long filenames, an unzip utility that supports long filenames (such as
WinZip) is recommended. If you use WinZip to unzip the files or if you use the
appropriate switch, then they will probably be placed in the proper directories
automatically. You can choose to edit any of the .htm files if you wish.

You will also need to create a directory named KEYWORDS in your WINS directory.
This location is hard-coded into the program, and will be used to hold all your
keyword files. Keep reading for more info.



USE:
Add a form to a web page (see example below). Your users can then use that form
to enter a keyword and jump to a predetermined page on your site. This can be
used to launch wcNav clients or connect to remote Internet sites as well.

All keyword files must be stored in a directory named KEYWORDS inside your wc5
directory. If your wc5 directory is named d:\WINS, then the keyword directory
would be at d:\WINS\keywords -- if your wc5 directory is at c:\wc5, then the
keyword directory would be c:\wc5\keywords.

The keyword files are all plain text files -- you can use Notepad or something
similar to create them. The name of the file is the name of the keyword, with a
.kwd extension -- that is, if you want someone to type "HELP" to go somewhere,
then name your keyword file HELP.KWD. The first line of the file should be a
description of what the keyword does -- this is used when the keywords are
listed. The next line is where the magic starts.

If the second line is a --- (that's three hyphens, no more and no less), then
all users who enter that keyword will be taken to the URL on line 3. If the
second line is the name of a security profile, then the entire document is
checked -- users with a primary security profile that matches the security
profile listed on any even-numbered line will go to the URL listed below. If no
matches are found, the user will see the invalid.keyword.security.htm file.
This gives you some power to your keywords -- a keyword to a private area could
take one user to the private area, and another to a page explaining how to pay
for that private area.



KEYWORD EXAMPLES:
The following keyword files are included for examples:
  HANDBOOK.KWD: Shows how you can use a keyword to link to another site.
  HELP.KWD: Shows how you can use a keyword to link to a page on your own site.
  INBOX.KWD: Shows how you can run a client (or open the inbox).
  LIST.KWD: Shows how you can provide a keyword to give a list of keywords.
  OTHELLO.WKD: Shows how you can link to a wcCode application.
  POKER.KWD: Shows how you can run a client. Also shows different responses for
    different users, based on their security profile.
  QWK.KWD: Another example of running a client.

This is not meant to be a comprehensive list of keywords, by any means. I
brought this feature online with 20 keywords, and a couple days later had about
35 keywords, and I'm continuing to add more. This can be a quick and easy way
to get places, if you use it well. You could even use it to jump to specific
conferences or file areas, without having to display a huge list of all the
available conference or file areas, which makes it nice for people who know
where they want to go.



FORM EXAMPLE:
Here's an example of the form you might want to use on your pages. I recommend
using this form somewhere on every page on your site, if practical (preferably
at the same place on each page, so your users get used to seeing the keyword
box and know where to enter their keywords).

<TABLE WIDTH=150 ALIGN=right CELLPADDING=4>
<TR><TD ALIGN=center>
<form method=get action="/code/html-keyword">
<B><I>Enter a <A HREF="/code/html-keyword?action=list">keyword</A>:</I></B>
<input type=hidden name="action" value="jump">
<input type=text name="keyword">
<input type=submit value="Jump!">
</form>
</TD></TR></TABLE>

The first and last lines of code are used to make a table that is squashed
against the right side of the page -- it makes the keyword box less obtrusive,
and still allows you to put a graphic (like your logo) to the left of it with a
nice balance to the page. You can remove the table tags if you want, or edit
the text of the form as needed. The hidden value is necessary, as are the name
of each of the values, but as you can see from the cannot.find.keyword.htm and
the keyword.list.htm, there are a lot of options available.



SECURITY:
Since users can't get to the keywords directory, they can't make their own. And
since you can have the same keyword do different things for different users,
you could even provide keywords to sysop-configuration utilities that would not
do anything (besides displaying the invalid.keyword.security.htm file) for
users that don't have sysop access. Plus, they will still need access to the
clients if you provide a wcNav client link.

This won't hide URL's, though -- once the user goes to wherever the keyword
takes them, they'll see the URL where they're at, so this isn't suitable for
trying to keep people out of certain areas unless additional security measures
are in place.



LEGAL MUMBO-JUMBO:
This program is being released as freeware, but *NOT* to the public domain. The
difference is that you are allowed to use this program for free, but there are
some restrictions. You are also allowed to distribute this program, as long as
there is no fee charged for the distribution (this includes any fee to cover
the cost of distribution) without the express written permission of the author.

Unless you have express written permission from the author, you are NOT allowed
to do any of the following:
   include this program in your own applications
   reverse engineer or decompile this program
   modify this program in any way (does not apply to modifying HTML pages or
        keyword files associated with this program)
   represent this program as your own

This program is not guaranteed or warranteed. There is no promise, explicit or
otherwise, of suitability to any particular purpose. Use at your own risk. By
using this program, you agree to hold the author harmless for any damage caused
to your system, or by the inability to use this program for the purpose for
which it was designed. In other words, no matter what happens, don't blame me!



FUTURE VERSIONS:
If there are additional features or functionality you would like to see added,
or if you just have some comments about this program, you can contact the
author at earl.borah@bbs.chemek.cc.or.us to make suggestions. The author may
choose to charge for any future versions of this program at any time, and
without notice.

As for support...I almost didn't release this program at all, because I wasn't
sure I wanted to provide support for it. I have a feeling that there will be a
lot of questions on this. Please, PLEASE, **PLEASE**, before you email me with
questions about how to make this work, make sure you have triple-checked the
documentation, triple-checked your HTML, and triple-checked the file locations.
I'll be willing to help with genuine problems, but if I hear anybody ask "Why
don't the keywords work when I put the .kwd files in my c:\wc5\data directory?"
or "Why don't the keywords work when I name them MyKeyword.htm?", then I may
just shake my head and refer you to the docs.