Matt's Whois (C) Matt Wilson 2001
=================================

Introduction
=-----------

Matt's Whois (MWhois) is a free whois lookup script licensed under the GNU
Public License (GPL - see COPYING for more details) written for both PHP and
Perl to make sure that almost anyone can use it on their site. The script uses a
template system so it can integrate easily with existing web pages and sites.

Contents
=-------

This document is split into various sections, they are;

1. Getting started
2. Simple configuration
3. Custom configuration
4. Additional templates
5. Customising templates
6. Updated servers.lst files
7. Credits and contact

1. Getting started
=-----------------

The first thing that you need to do in order to use this script is to download
it, but as you are reading this document i'm guessing that you've already
downloaded it, I can also assume that you have succesfully extracted the files
from within the mwhois archive.

The next thing to do in order to make sure that the script works on your site
is to upload the files that you have got onto the web server, most people will
use an FTP client to do this and i'm not here to teach you how to do that, so
thats upto you to discover (if you don't already know how to do it). Upload all
the files in this archive onto your webserver into a directory (mwhois/ would be
a good choice I feel) that is accessible via the internet (ie
http://mydomainname/mwhois/).

If you are using the Perl version of this script and your website is hosted on a
Unix webserver then you need to change the file mode/permissions to 0755 (CHMOD
or Change file mode) in order for the script to execute, you may also wish to
perform this operation for the mwhois_admin.cgi file. For the Perl version to
function correctly you may also need to set the "$base_directory" variable at
the top of the script to the same directory in which you have place the other
Matt's Whois files (the themes and config.cgi), otherwise Matt's Whois will not
be able to locate them. The PHP version should not require this alteration.

By now visiting the script in a browser (http://mydomainname/mwhois/mwhois.cgi
for Perl users and http://mydomainname/mwhois/mwhois.php for PHP users) you
should be presented with the default template's search screen. If this does not
happen you can check the file permissions etc and then if all else fails you
may e-mail me for assitance at matt@mattsscripts.co.uk.

2. Simple configuration
=----------------------

Basic configuration of the script can be achieved via the MWhois admin script,
if you are using the Perl version then this script is called mwhois_admin.cgi,
if you are using the PHP version then this script is called mwhois_admin.php.
Whichever version of the script you are using the admin script is located in the
same directory as the main script (mwhois.php or mwhois.cgi) and should be
accessed in the same way.

Once the page loads you can follow the instructions and easily configure the
script using the form provided. By using the first drop down menu you can
select which template you would like to use with the script (see section 4.
Additional templates and section 5. Customising templates for more information
on templates). Secondly is the option of whether or not to use the global header
and footer templates, when turned on they appear at the beginning and end of
every page the script handles. Finally and most importantly the script displays
a list of all the top level domains supported by the version of the servers.lst
file you have installed (see 6. Updated servers.lst files), simply check the box
next to each top level domain you would like to use and the script will be
configured for use with it. When all this is done click the "Get config file"
button located at the bottom of the page and you will prompted to download a
file, download the file and save it as either "config.cgi" for the Perl version
of the script, or "config.php" for the PHP version of the script. The final
step in configuring MWhois is to upload this downloaded file onto the webserver
in the same directory as the main script (either mwhois.cgi for the Perl version
of mwhois.php for the PHP version), the file will already exist so you may be
asked whether or not to overwrite the file on the server, you should overwrite
the file on the server with the local file.

3. Custom configuration
=----------------------

Custom configuration involves manually editing the config.cgi or config.php and
changing the values that are present to one's more suiting to your needs. This
is a generally easy process but can cause problems with the script's execution
if performed incorrectly and so I am going to suggest that only more advanced
users should perform this step. At present there are not very many options that
could be changed, either manually or with the administration script and the only
option I would imagine people would want to change manually is the order in
which the Top Level Domains appear in the drop down menu on the search page.
This is merely set using an array within the config file and is easily altered
providing you know how to alter it. If anything goes desperately wrong you can
use the admin script and produce another config file or simply reupload an
existing file.

4. Additional templates
=----------------------

Additional templates are available for download from the Matt's Whois script
main page, as of writing the only templates that are available are the default
templates for English and German. To use one of the extra templates all you
need to do is to download the archive containing the template, extract it into
a temporary directory on your computer and then to upload all the extracted
file into a sub-directory (english/ for the default English template and
deutsch/ for the default German template) within the main MWhois directory (ie
you will have /mwhois/english/ or /mwhois/deutsch/ with all the files within
these directories). After you have done this you can either use the admin script
to generate a config file as the admin script will automatically recognise the
newly installed templates provided that they have been installed correctly, or
you can manually edit the config file to use the new template.

5. Customising templates
=-----------------------

The template's config files (templates.cfg and titles.cfg) are plain text files
which contain information for the usage of the template, within the
templates.cfg are a list of "flags" corresponding to various pages of the script
, along with each of these there is a filename which should be loaded as that
page's template. The titles.cfg file is very similar although it contains what
the title should be for each page. While these files can be changed to
accomodate new file names and page titles, I would recommend that they are left
with there current values.

The main part with customising templates are the template files themselves
(*.tml) which contain plain HTML with a few inserted extras that are used by the
main script to decide where to place information obtained during the process
such as RAW whois data etc. A list of these and what the script uses them for
are shown below;

	[>DOMAIN<]	->	The domain name specified to search for.
	[>EXT<]		->	The top level domain of the name to search for.
	[>RAWOUTPUT<]	->	The raw output from the whois server.
	[>WHOIS_SERVER<] ->	The host name of the whois server used for this
				query.
	[>AVAIL_LIST<]	->	A list of the available domains obtained from a
				global search or wizard search.
	[>UNAVAIL_LIST<] ->	Same as [>AVAIL_LIST<] except this is a list of
				the domains that are unavailable.
	[>ERROR_MSG<]	->	When an error occurs the script (by default)
				shows error.tml as the main template file and
				replaces this with the error message produced by
				the script.
	[>EXT_HTML_LIST<] ->	A <SELECT> list of all the extensions the script
				is configured to support.
	[>EXT_LIST<]	->	Another way to list the extensions configured to
				support, shows each on a new line, ie;
				com<BR>net<BR>org.
	[>SCRIPT_NAME<]	->	The name of the script being executed (either
				mwhois.cgi or mwhois.php by default).
	[>TITLE_BAR<]	->	The page title for the page being shown, taken
				from the titles.cfg file.

By placing these values in the template files at various locations you can
customise the templates to your own use or create your own brand new templates.

6. Updated servers.lst files
=---------------------------

Within the main MWhois directory there will be a file called "servers.lst", this
file contains data required for the script to run, it contains information about
each top level domain that is supported and which server to query etc. Every
now and again a new "servers.lst" file is released containing updated whois
server data. These are usually announced either on the Matt's scripts mailling
list (e-mail to: subscribe@mattsscripts.co.uk) or announced on the Matt's
scripts front page. Either way, the latest version of the "servers.lst" file is
available for download from the following URL:
http://www.mattsscripts.co.uk/servers.lst and should be uploaded onto your web
server in the main MWhois directory, along with the main script and theme sub
directories.

7. Credits and contact
=---------------------

Both the Perl version and the PHP version of Matt's Whois were written from
scratch by Matt Wilson <matt@mattsscripts.co.uk> and is licensed under the GNU
Public License (GPL - See COPYING for details).

Other credits go to various people that will be listed here as soon as I can
remember them ;).
