1. Purpose
----------

This guestbook has been specially designed for multiuser sites: a
site-wide guestbook.pl file can be reused by multiple users by
"require"ing it in their own guestbook.cgi files. Appearance is
configurable through the use of "template" files, which can be edited
by any GUI Webpage editor.

2. Multi-User setup
-------------------

a) The administrator should put the guestbook.pl script to a place
accessible to all users of the system (such as
/usr/local/lib/guestbook/guestbook.pl)

The administrator should also make sure that the users have the right
to run cgi scripts (Set "Options ExecCGI" in /etc/httpd/httpd.conf),
and that those cgi scripts run under the user's privileges (suexec).

Moreover, certain templates use image links.  These images should be
copied to a place which is visible from the web (Apache's "icons"
directory), and the templates should be adapted, if needed (by
default, the images point to
/icons/guestbook/<template>/<image>.gif). If you just copy guestbook's
"icons" subdirectory to /usr/local/httpd/icons/guestbooks, the
templates should work as is.


b) Each user then just copies the guestbook.cgi example from
/usr/local/lib/guestbook/examples/guestbook.cgi to his Web directory,
and customizes it to his taste.  The following variables can be set in
this script:

 Address where the program sends mail notices for new additions to the
 guestbook.  By default, user@localhost is used, where user is the
 Unix user as who the script runs.

  $mail='user@somewhere.org';

 If you don't want any mail to be sent, just set it to the empty
 string:

  $mail='';


 Username (used in the title certain templates: Welcome to xyz's
 Guestbook):

  $username="Tom";


 Template: Path to a html template which describes the appearance of
 the guestbook page.  By default, a file named
 "guestbook-template.html" in the same directory as guestbook.cgi is
 used. If none is available, an internal template is used.

  $template='/usr/local/lib/guestbook/templates/darwin.html';


 The last line of guestbook.cgi should call the actual script:

  require "/usr/local/lib/guestbook/guestbook.pl";


3. Single-user setup
--------------------

The user needs privilege to run cgi scripts.  If so, he can just
install guestbook into any of his directories, and require it from his
guestbook.cgi file:

  require "/home/tom/guestbook/guestbook.pl";

If you don't have access to your webservers icon directory, choose
another directory, and adapt the links in the templates files.


4. Guestbook Template Syntax
----------------------------

 The guestbook template file is mostly a html file, and could even be
 edited using a HTML editor such as Netscape or Frontpage.

 The template contains must contain two markers to mark the area where
 messages will be displayed: BEGIN_MESSAGE and END_MESSAGE, and a
 number of variables (such as ${mail}, ${body}, ${$maillink}).  The
 text between those markers are repeated once for each message, and
 the variables are substituted with their value:


 For each message:
   ${email}     - the signer's e-mail address
   ${fullname}  - the signer's full name
   ${maillink}  - a mailto: link pointing to the signer's email
                  address (and having the full name as text)
   ${body}      - the body (contents) of the entry

 Global variables:
   ${username}  - the username variable of the guestbook.pl script.


5. Other goodies (to be placed in the same directory as guestbook.cgi)
----------------------------------------------------------------------

 thanks.html file - If it exists, this file is displayed to any
                    visitor after he submitted a new entry. If it
                    doesn't exist, the visitor is sent back to the main
                    page (containing the submission form and all entries
                    that have been submitted)

 whoru.html file - This file is displayed to visitors which neither
                   supply their name nor their e-mail address

 guestbook.txt file - The actual guestbook.  It is a plain text file,
                     and can easily be edited (for instance to remove
                     offensive entries/test entries). However, when
                     hand editing this file make sure to respect its
                     format: Entries are separated by a period on a
                     line by its own. If a visitor actually entered a
                     line solely composed of periods, then an extra
                     period is added automatically to distinguish it
                     from the "end of message" marker.

6. Prewritten templates
-----------------------

 The following prewritten templates are available in the "templates"
 directory:
   default.html  - the default template (same as compiled in:
                   rectangular framed colorful boxes.  Needs no images
   darwin.html   - rounded quarterframes, as found on the "Darwin
                   Awards" web site's slush pile
   frames.html   - full rounded frames (green) on a light green background
   simple.html   - simple textbased without tables
   slashdot.html - every self-respecting geeks' favorite: Slashdot look
