This file comes with the form-mail package, a combination Perl program
and HTML document that allow users of World-Wide Web browsers to
submit comments to the maintainers of a WWW server.

Please send comments and questions regarding any part of form-mail to
Reuven Lerner, reuven@the-tech.mit.edu.  I am particularly interested
in finding out about potential security holes, although I certainly
wouldn't mind receiving bug reports and feature ideas.

This package has been in use for some time at The Tech, MIT's student
newspaper.  You can access an on-line version of it at URL

    http://the-tech.mit.edu/Info/test-comment.html

Before I continue, a bit of legal hoopla:

------------------------------------------------------------
This package is Copyright 1994 by The Tech. 

Form-mail is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2, or (at your option) any
later version.

Form-mail is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with Form-mail; see the file COPYING.  If not, write to the Free
Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
------------------------------------------------------------

A quick note: I realize that this isn't the most elegant or secure way
to send comments to the webmasters at a site; at the very least, there
is a <mailto> tag that should do the job.  But hey, that tag doesn't
work on all browsers, and this seems to work well enough for our
purposes.  I hope that it works well enough for you, but as I said,
there are certainly other solutions to this problem.

Installing form-mail is quite simple.  You will need the following:

(1) Perl, a wonderful language for doing almost anything you would do
    with a shell script, and much of which you might do with C.  Perl is
    freely available from a number of sites, including by anonymous ftp
    from prep.ai.mit.edu in ~ftp/pub/gnu.  If you are new to Perl, I
    strongly suggest that you buy a copy of "Programming Perl," published
    by O'Reilly and Associates.  Another book, "Learning Perl," has hit
    the markets in recent months; while I haven't read it myself, I have
    heard generally good things about it.

    If you have trouble installing Perl on your system, I suggest that you
    read the Perl FAQ (list of frequently asked questions), available by
    anonymous ftp from convex.com in ~ftp/pub/perl.  If that's not
    enough help, try asking on the newsgroup comp.lang.perl.

(2) A World-Wide Web server.  We use NCSA httpd at The Tech, which you
    can get by anonymous ftp from ftp.ncsa.uiuc.edu.  I haven't tried 
    form-mail with any other servers, but I wrote it to conform with CGI
    (common gateway interface) specifications, so it should work with
    recent versions of Plexus and CERN httpd.  The CGI specs, by the way,
    are available on the Web at URL http://hoohoo.ncsa.uiuc.edu/cgi.

    If you don't already read the newsgroup comp.infosystems.www, you
    probably should, especially if you are a Webmaster at your site.

Assuming all of that is in order, 

(1) Edit form-mail.pl.  This Perl program is executed whenever a user
    presses the "Send comments" button on comment-form.html.  (If you use
    GNU Emacs, the funny -*-perl-*- at the top of the document will place
    Emacs in perl-mode even if .pl isn't in your auto-mode-alist.  And if
    you didn't understand the previous sentence, don't worry about it.)

    There are several things that you will probably want to change in
    form-mail.pl:

    (a) $mailprog.  This can be any program that accepts mail sent to
        its standard input (i.e., if you can type `foomail <
        /etc/hosts', you can use foomail as $mailprog.  I used to use
        /usr/ucb/mail (aka mailx) on our system until someone pointed
        out the potential security holes that could crop up in such
        cases.  I have since switched to sendmail, which while
        infamous for being insecure, is still much better than plain
        ol' mail. 

    (b) $recipient.  Please change this to the username or mailing
        list that you deem appropriate.  Previous versions of
        form-mail set this to archive@the-tech.mit.edu; we got quite
        a number of spurious messages from users at other sites.

    (c) You might want to change the mail message sent to $recipient.  At
	the very least, you'll probably want to describe your WWW server as
	something other than "The Tech's."

    (d) Last, but not least, you will probably want to change the end of
	the file, in which we print a message to the WWW user thanking him or
	her for sending comments.  This can be as simple or elaborate as you
	want; you could even use a while loop to print out the
        contents of a file containing valid HTML.
        
(2) Place form-mail.pl in a directory that can be used for CGI
    programs.  In NCSA httpd, this is done by adding a ScriptAlias
    directive to the srm.conf configuration file.  On our system, this is
    /usr/local/etc/httpd/cgi-bin; our srm.conf has the following line:

    ScriptAlias /cgi-bin/ /usr/local/etc/httpd/cgi-bin/

(3) Edit comment-form.html to your taste.  This is an HTML document,
    and should follow those specifications as closely as possible.  Good
    documentation on HTML is available at URL

    http://www.ncsa.uiuc.edu/General/Internet/WWW/HTMLPrimer.html 

    Note that comemnt-form.html uses fill-out forms, a feature that is due
    to be in HTML+ (a forthcoming enhancement to HTML).  Some good
    documentation on forms is available at URL

http://www.ncsa.uiuc.edu/SDG/Software/Mosaic/Docs/fill-out-forms/overview.html

    (Yeah, that's a bit too long for my taste, too.)

    Be sure to change the "action=" setting in comment-form.html if
    you have changed the name or directory in which form-mail sits.

(4) You might have to send your server a `kill -1' to tell it to
    reread some of its configuration files.  It can't hurt, in any
    event.

Things should now work!  If you have problems, look at the checklist
in the file called HELP that should have come with this distribution.
If nothing there seems to solve your problem, send me mail at
reuven@the-tech.mit.edu.

Good luck, and happy Webbing!

Reuven
