WILMA: Web Information-List Maintenance Agent (version 1.xMN)
----------------------------------------------------------------------------
     Copyright 1997 by Mark Nottingham
     This is derivative software; see wilma.license for more information.

     Original Copyright © 1995 by E-Doc
     WILMA Development Team: Andrew Williams and Daniel K. Appelquist
----------------------------------------------------------------------------
	
Installation

First, please verify that you have a complete installation: read the README.

WILMA 1.xMN exists as a group of scripts, libraries and configuration files 
in a small directory tree. These scripts have been written and tested with 
Perl 5.003; Perl 5 or above is required by the scripts. To see what
version of Perl your system has, type 'perl -v' (without the quotes) on
the command line.


---------------------------------------------------------------------------

A) Install Location

By default, the installation is configured to run entirely in a
ScriptAlias directory (e.g., cgi-bin); there are a number of ways to
achieve this.

  1. If you have the appropriate permissions, unpack the distribution in
     the cgi-bin directory of your server; name the directory uniquely if
     you wish to run more than one instance of WILMA.

  2. If you have access to the server configuration (or to your sysadmin),
     you can configure additional directories to be script-enabled; see
     your server's documentation (with Apache, use ScriptAlias in
     srm.conf).

  3. If your server is set up to allow it, you can use access control
     files (e.g., .htaccess) to enable script execution in a directory.
     See your server's documentation. Note that this has the potential to
     open Wilma up to prying eyes, because all of the associated files 
     may be readable by the Web server. Consult you sysadmin.

 If you don't wish to (or can't) put the entire distribution in a
 CGI enabled directory, you can put only the scripts needed there, and
 edit wilma.conf to point elsewhere for other files (such as headers
 and data); see wilma.conf for more information.

 Once you've unpacked it, rename the distribution directory to suit your 
 taste; its name will show up in the URL.


----------------------------------------------------------------------------

B) Script and Directory Configuration

There may be minor modifications needed to the actual scripts and the data 
directory to allow Wilma to function.

  1. Edit the first line of each script to reflect Perl's location. for
     instance, #!/usr/bin/perl will be the first line if Perl is located
     at /usr/bin/perl. (Type 'which perl' to find it)

**2. The 'data' directory MUST be writable by the UID running the Web
     server; this means that it should either be owned by that user (chown
     user data), or world-writable (chmod o+wrx data). Both of these have
     security implications; talk to your sysadmin about it if you're unsure. 

  3. Some systems may have a problem resolving the location of the
     libraries (wilma.conf, www-lib.pl and wilma-lib.pl) properly. If this
     causes problems, edit the scripts to reflect the full path to them.

The scripts are 'list', 'add', 'edit', 'index', 'search', and
'admin/wilma-admin'.


----------------------------------------------------------------------------

C) Edit wilma.conf

wilma.conf is the central location where you can customise WILMA to your
content. It is split into several sections, starting with Categories.

* Starting with version 1.35MN, wilma.conf.short is provided for the 
  convenience of those familiar with Wilma's operation; it is the same as
  wilma.conf, except it doesn't have explanatory comments included. If you
  use this, YOU MUST RENAME IT TO 'wilma.conf'.

1. [Categories]

1.1 Edit the category list to reflect the categories of information you
    will be hosting. You can declare as many or as few as you wish.

@Categories = ('Magazines: Fiction / Poetry',
               'Magazines: Music',
               'Magazines: Reviews',
               'Other Magazines',
               'Newspapers',
               'Other Resources');


1.2 Then, edit the abbreviation list. The order of the abbreviations
    should be the same as the order of the items in the category list. The
    abbreviations do not need to be limited to three characters, but should be
    kept short and should not contain spaces, periods or special characters.

@Abbrevs = ('mfi',
            'mmu',
            'mre',
            'mot',
            'nws',
            'oth');




2. [Paths]

2.1 Declare the full path to the directory where WILMA is installed.

$wilma_path = '/home/httpd/cgi-bin/wilma/';


2.2 If you wish to mail the 0 when new submissions arrive,
    declare the full path and options for Sendmail on your system. The -t
    option enhances security in some implementations.

$sendmail = "/usr/lib/sendmail -t";



3. [URL's]

3.1 Edit the URL section. If you are doing a default installation, you will
    only need to change $server_name and $dirURL to reflect the base URL for
    your server and path to the URL where WILMA is located.

$server_name = "http://www.here.net";
$dirURL = "/cgi-bin/wilma";

    There are several other URL specifications that should not need to be
    modified for most installations; a notable exception is $addURL, which
    should be put into a protected directory if you wish to control addtions.



[Configuration]
4. [Look and Feel]

4.1 Set wilma_name to the title for your list.

$wilma_name = "Wilma Resources";


4.2 Set the names of the data fields for submissions; pay special attention
    to the restrictions listed in the configuration file.

$title_phrase = "Title";
$subtitle_phrase = "Subtitle";
$full_desc_phrase = "Full Description";


4.3 If you wish to have additional text at the top of the addition form, 
    set $add_text. Leave blank to exclude; entry will be enclosed in 
    <P> tags.

$add_text = "";


4.4 Set the Background Color you wish your pages to have; this must be in
    the standard format of #rrggbb, where rr, gg, and bb are the hex values
    for the red, green and blue components.

$bgcolor = "#F3F3F3";


4.5 Set the location (as an IMG) for the icon to be displayed for new
    items. For best results, set WIDTH, HEIGHT, and ALT tags. Please note that
    this must be in single (not double) quotes.

$new_pic = '<img src="/images/new.gif" height=10 width=25 alt="NEW!">';


5. [Submission Options]

5.1 Set preferences for full descriptions and URL's in submissions. you
    can either disallow them completely, make them optional, or mandate them.
    See the wilma.conf for more details.

$req_long = 1;
$req_URL = 1;


5.2 If you wish to allow HTML tags in full descriptions, set $req_html to
    1; otherwise set it to 0.

$req_html = 1;


6. [Display Options]

6.1 $sortfunc determines how items in category listings will be sorted. If
    you want to see them in alphabetical order, choose "by_title". If you wish
    to present them in order of addition to the database, choose "by_date". 
    This is handy for what's new lists.

$sortfunc = "by_title";


6.2 $cat_format allows you to specify whether a listing in a category index
    will link to the full description or directly to the URL. If it is set
    to the latter, the user can still get to the full description (assuming
    it exists) by way of a 'description' link after the item's title. If
    full descriptions are disallowed, this MUST be set to link to the URL. 

    If you do link to the full description, you can choose between two formats,
    single line and two line. Try each to see which you like best.

$cat_format = 2;


6.3 If you want to include the e-mail address of people who make
    submissions in full descriptions, set $inc_email to 1. Users will be
    warned in the submission form if their e-mail address will be included. 
    (It is probably a good idea to disable this if getting reliable e-mail
    addresses is important to you, since many people will submit a false
    address if they know it will be published)

$inc_email = 0;


6.4 If you want to list when something was submitted in the full 
    description, set $inc_date to 1; otherwise, set it to 0. Note that 
    submissions which must be approved, or those that have been edited, will 
    show the newer date instead of the original date.

$inc_date = 1;


7. [Index Options]

7.1 If you want to show counts of items in each category (assuming you're
    using index), set $index_count to 1; to suppress the count, set it 
    to 0.

$index_count = 1;


7.2 $cache_minutes sets the number of minutes to cache the contents of 
    wilma_index; by using this properly, you can improve performance for 
    large indexes. Note that the cache is cleared whenever a modification is 
    made to items in the database; the only attributes which may age during 
    caching are expiry times and "new" flags on items in the main index.
    $cache_minutes only effects index; to disable it, set it to 0.

$cache_minutes = 20;


8. [Administration Options]

8.1 If you want control over what gets added to the database, set $direct
    to 0. If you don't mind people being able to directly add items, set it
    to 1.

$direct = 0;


8.2 If you wish to expire all entries a set number of hours after they are
    added to the database, set $expire to the appropriate number; to disable 
    expiry, set it to 0.

$expire = 0;


8.3 Set the time (in hours) that an item will be considered 'new', and be
    flagged as such with an icon.

$new_hours = 48;


8.4 Enter the E-mail address of the maintainer of the archive. This must
    also be in single (not double) quotes.

$maintainer = 'me@here.net';


8.5 If you wish the maintainer to be notified each time someone submits an
    item, set $notify_admin to 1; otherwise, set it to 0.

$notify_admin = 0;


9. [User Editing Options]

9.1 To allow users to edit or delete their entries after submission, set 
    $edit to 1; set to 0 to disable this.

$edit = 0;


9.2 If you wish, users can be notified of their editing key by e-mail; set
    to 1 to enable.

$notify_user = 0;



10. [Searching]

10.1 If you are implementing searching, edit the $reindex variable to
     include the text of the command to re-index your site.

$reindex = "/usr/local/bin/swish -c /home/httpd/cgi-bin/wilma/swish.conf"


----------------------------------------------------------------------------

D) Headers

Headers and footers are appended to every page that the list and index
scripts send out. With them, you can control the look and content of your
Wilma installation.

Generic headers and footers (header.html and footer.html) are supplied 
in the 'headers' directory; you can modify these as you see fit. The header 
should omit the following lines, as they are supplied by the script;

<HEAD><HTML>
<TITLE>[title]</TITLE>
</HEAD><BODY BGCOLOR="[bgcolor]>

The footer should omit;

</BODY></HTML>

Besides having general headers and footers, you can also specify them
for individual categories, as well as the main index page and the search
page. They all follow the format

name_header.html
name_footer.html

To modify an individual category's listings (its index as well as full
descriptions, if they're available), name would be the abbreviation of
that category. For instance, if your category abbreviation is abb, you 
would use abb_header.thml and abb_footer.html to append headers and
to the listing as well as the entries of that category.

To modify the main index, use

index_header.html
index_footer.html

and to modify the search page, use

search_header.html
search_footer.html


----------------------------------------------------------------------------

E) Security

You will more than likely want to protect the administration functions
from tampering. Consult your server documentation (on Apache, use a
.htaccess file). 

WILMA 1.xMN is distributed with a template htaccess file; to implement,
edit it to suit your needs and rename it to .htaccess (it will be a hidden
file). Be aware that .htaccess user- and  host-based authentication are not
foolproof security measures, although they will deflect the curious. A 
determined cracker can circumvent them.

Also, be aware that anyone who has access to your data directory (in many
cases, any user on the machine) can read the configuration and data for 
Wilma, including editing keys.

Because all Wilma pages are served by CGI, there is no danger from Server
Side Includes being slipped into your pages.


----------------------------------------------------------------------------

F) Searching

If you want to implement searching, make sure swish is installed, and then
edit the swish command line which is at the top of the search script.