
 PERLFECT SUBSCRIBE v2.0

 (C)1998-99 Perlfect Solutions
             www.perlfect.com



REQUIREMENTS

This software is designed to work on UNIX-like systems. If you
are on NT, the setup utility will not work and you will have to
install it manually. I'm not even sure if there's any hope of
getting it to work at all even with a manual installation.

Other that that, there are no special requirements. Just
a recent version of Perl (5.004+ is recommended) and CGI.pm
(which is present in any web hosting system)



NOTE ON DOWNLOAD

If you tried to download subscribe-2.0.tar.gz but you ended up
with a file ending with another extension (_tar or tar_tar) 
rename the file to the extension it should have. Some browsers
play nasty tricks renaming files to odd extensions...



INSTALLATION

Upload the distribution archive subscribe-2.0.tar.gz onto
your account at your web server machine. Put it in a temporary
directory. (not in your cgi-bin) Use telnet to login to your
account (see NO TELNET if you don't have telnet access to your
account) and use the command

        tar xvfz subscribe-2.0.tar.gz

to extract the files in it. The files will be extracted in
a new directory called subscribe-2.0. Go to that directory
and run the setup utility with the command

        perl setup.pl

The setup utility will guide you through the rest of the
installation.



INSTALLATION SERVICE (NOT FREE)

If this is not easy enough for you, you can always hire us
to install the script on your machine ($100 fee). Mail
installation@perlfect.com to arrange for a paid install.



NO TELNET

You have no telnet? Too bad. There goes the setup utility.
Are you sure you do not have telnet access? Perhaps you just 
don't know about it. Use a telnet program (on unix just
type telnet and the hostname, on windows there must be
a telnet.exe program in you windows directory that you
can run to connect to your host) and try connecting with
your ftp username and password. If that doesn't work, ask
your host to provide you with telnet access. They should.

If you absolutely can't find a way to telnet to your
account, you'll have to resort to manual installation.
In that case, may the force be with you, but please don't
send mail asking for handholding. There are many people
using our scripts and we'd rather spend our time making
them better for the benefit of everyone than helping
a particular person get it working.

Nevertheless, here are some instructions that will
probably be enough to get you going: 

1) First of all open the archive you downloaded
   on your local machine. WinZip open .tar.gz files;
   if you have trouble, see the NOT at the top of this
   README about browsers screwing up extensions.

2) Upload the entire content of the distribution
   on your account as it is, inside your cgi-bin.

3) Change the permissions of all the files to 755.
   Your ftp program should have a way to do that.
   (if you see the word chmod, that's it) Now set
   the permissions of subscribe.cgi to 4755.

4) Open the file search_conf.pl and edit the variables
   in there to reflect your site's URLs and paths as
   well as your name and email. It should be obvious
   what to do from the existing values.



USAGE - SUBSCRIPTIONS

Assuming you cgi-bin is reachable by the URI /cgi-bin/
you will need to use the following form to allow users 
to subscribe to your mailing lists from your site:

<form method="post" action="/cgi-bin/perlfect/subscribe/subscribe.pl">
<input type="hidden" name="op" value="add">
<input type="hidden" name="list" value="my-list">
<input type="text" name="email" value="">
<input type="submit" value="Subscribe!">
</form>

To have different subscribe boxes that will let users
subscribe to different mailing lists, substitute the
value 'my-list' in the form above with whatever you want
to name each list. Don't use whitespace or funny characters
in list names. Stick to letters, numbers, underscore and dash.

You need to do nothing to "initialize" a list. Whenever
the fist user subscribes to a new list name, the script takes
care of creating it. All users and all lists are kept in
the same file mailing_lists.txt which should be wherever the
script is installed.

If you open the file you'll notice that each line looks like
nick@perlfect.com:3131444:list_1,list_2
The first field is the email address of the subscriber,
the second field is a numerical ID generated by the script
the first time this user subscribes to a list. It is used
to identify the user if the user need to unsubscribe from a
list. The thrid field is a comma-separated list of all
mailing lists that the user is subscribed to.

When a user fills the form and subscribes to a list, a welcome
email is sent out to the new email address. This email contains
a URL that will remove the user from that list if clicked,
so that the user can keep this email to unsubscribe later.



USAGE - MAILER

Type the location of the mailer script into your browser
window. If you used the setup utility that should look like
http://yourdomain.com/cgi-bin/perlfect/subscribe/mailer.cgi

You will be prompted for a password. This is the password
you chose during the setup of the script. Enter it to 
be transferred to the mail editor. From then on, things
are pretty obvious. You select one or more lists, you
type your message and you send it out.



CUSTOMIZING RETURN PAGES AND MAIL MESSAGE

There are three different return pages that result from
operations of the subscribe script. One is the result
of a user subscribing to a list, the other is the result
of a using unsubscribing from a list and the third
is an error page that is returned when something goes
wrong. There is also an email message sent to the user
after subscription. You can customize them all by editing
the files in the 'templates' directory which should be
wherever you installed the script.

You'll notice that they all contain some HTML comments
like <!--cgi:email--> Those are directives to the script
that get replaced with dynamioc values at each execution.
You can move the around, you can use them more than once
in a file, and you can even delete them if you wish.
