modtool v2.0
============

(C) Christian Alice Scarborough 1996
Email: ccs95@aber.ac.uk
Released under the GNU public licence - see file COPYING for details

Abstract
--------

modtool is a general purpose Perl program for moderating mailing lists
and/or Usenet newsgroups from a UNIX shell.  It does the following things. 

 o Displays submitted articles

 o Posts accepted articles, allowing the moderator to edit them first if 
   necessary.

 o Automatically checks for other moderated groups, and mails article to 
   next moderator in line if necessary.

 o Sends form rejection letters, prepared in advance, to the poster (further
   comments can be added, or a personalised reply sent if desired).

 o Cancels forged postings to the group

 o Creates and mails RFC1153 compliant digests either as articles are
   approved, or by reading the group.

 o Automatically replies to incoming submissions when used in conjunction
   with a mail filter.

 o Allows moderation of multiple groups/lists by using multiple
   configuration files.

Prerequisites
-------------

modtool requires the following to be installed on the UNIX system which it
is run from.

1) Perl v5.000 or greater

2) A pager (more should work, less is better)

3) A UNIX editor (if you want to use the editing facilities)

4) Mail to the moderation address stored in a standard UNIX mailbox file.

Caveat
------

modtool is my first ever Perl program.  It represents about 48 hours
coding time (including the time taken to learn Perl).  It is not neat.  It
is not efficient.  It is not likely to handle something extremely odd
happening in an incoming article (eg no Subject: field).  It does,
however, seem to work.  Use at your own risk.  I will attempt to support
it by email, but only as and when I have time, so you should consider it
UNSUPPORTED software.

If you do decide to use it, please send me email, so that I can inform you
when bugfixes and updates are available.  You can use modtool completely
free of charge, but if you find it especially useful then please bear in
mind that I'm an impoverished research student, and any donation you can
afford would not go amiss.

Installation
------------

o Unpack the files in this archive into a directory of their own.  Edit
the .modtoolrc file in your favourite editor, and change all the variables
so that they refer to your newsgroup or mailing list and setup.  All of
the variables are documented within the .modtoolrc file itself.  (Note
that lines beginning with a # are comments, and are ignored by modtool.)

o You may want to edit the 'rejections' file too.  The first word of each
line is the name of a file (in the working directory of the program) which
contains the text of a form rejection letter.  The rest of the line is a
short description of each letter that the program uses to help you choose
the letter you wish to send.  You can have up to ten of these letters.

o You should also edit the mod.sig file to contain the information you
want putting at the bottom of each message.  If you don't want a sig,
leave it empty, but it must be there, or the program will fail. (You can
change the filename by editing one of the variables though.)

Usage
-----

Modtool has several modes of invocation.  To help help on the command line
switches, type 

    modtool -h

TO run modtool, change to the directory containing the program and type

    modtool

The first message will be displayed.  Once you have seen the whole
message, you can either accept (post) it, reject it, junk (erase) it,
display it again, save it to a different mailbox, or quit.  You should
press the appropriate letter at the prompt.  The letter inside the
brackets is the one that you press (eg press 'j' to (J)unk an article). 
The 'n' and 'p' keys allow you to skip between all of the articles in the
file.

If you opt to post the article, you are offered a further menu that allows
you to send the article, edit the article you are about to post, to
list the article as it will be posted (note: this is a Good Idea, as the
program changes a lot of the headers around), or cancel and return
to the previous menu.  Canceling will not delete the current article.

If you decide to reject an article, a menu comes up detailing the stock
responses that you have written.  To choose one of these, press the
appropriate number (0-9), or you can write your own response. Once this is
done, you are given the opportunity to edit the reply, or
send it back to the poster.

Junking an article throws it away.  You can't get it back, so be careful
with this option.  It will ask you to confirm your action.

The save function copies the mail to another folder (the name of which is
again specified in the configuration file), and removes it from the
incoming post file.  This is in case people send mail to the moderators to
the submission address instead of the admin address.  You will be prompted
for a file name, but can just press return to use the default from the
configuration file.  If the file does not exist, modtool will ask you to
confirm creation of this file.

You can quit after any article (the current article will not be deleted).
When there are no more articles left, the program ends.

A note about multiple moderated groups
--------------------------------------

Modtool will automatically detect other moderated groups in the
Newsgroups: line of any post, provided that they exist on the news server
at the moderator's home system.  Modtool will assume that any groups
appearing before the moderator's group on the Newsgroups: line have been
seen by the appropriate moderator, and have been passed on by them for
approval.  Modtool will print a warning message if it makes such an
assumption, so you can check that it really has been approved.  If not,
you might want to save it out to a separate file for manual processing.

Modtool will also check if groups appearing after the moderators group in
the Newsgroups: line have been approved by PGP Moose.  Note that modtool
will not check the validity of the PGP Moose X-App: header - if the header
exists, it will simply assume that the signature is valid, and will
consider this article to have been approved by the moderator in question.
This means that if such approval has been forged, the article may later be
cancelled by a PGP Moose daemon.

If there are any moderated groups remaining, then modtool will take the
next such group on the Newsgroups: line and mail the article to the
moderator of that group.  Note that, unlike PGP Moose, modtool does not
alter the order of newsgroups within the header.  (The author considers
this sort of behaviour to be a Bad Thing.) 

Canceling articles
------------------

To use modtool to cancel forged submissions, use the following command:

   modtool -c < <article_file>

This sends out a cancel message for the article in question.  modtool
assumes the -c parameter if you invoke it as 'cancel'.  Thus I have a
symbolic link to modtool in my News directory, so to cancel an offending
article from within trn, I just type

  | cancel 

on the trn command line at the end of the message.

Auto-replying
-------------

You can get modtool to send out automatic replies to incoming submissions,
to acknowledge receipt, for example.  The syntax of the command is

   modtool -r < <incoming message file>

You can also create a symbolic link ending in "reply"  which will cause
modtool to assume the -r switch.  The idea here is that before your mail
filtering program saves a copy of each new message to the incoming file,
you should pipe the message to modtool.  Modtool will then send back mail
telling the sender that their mail has been received.  The method for
doing this varies from filter to filter, but here's the recipe that I use
in procmail

    :0
    * ^TOcomp(\.|-)org(\.|-)team-os2@ 
    {
        :0 c
        | modtool -r

        :0:
        cot
    }

Modtool will not cause any mail loops to occur, because it stores email
addresses that it has sent replies to that day, an will not send a reply
to any one address more than once in a day.

You can use the special symbol %subject% within the text of your reply,
which will be replaced with the Subject: line from the original mail.  See
the configuration file for more details.  

Digests
-------

Modtool provides a way for you to archive posts to your group or list in a
RFC1153 compliant digest.  It will even mail them out when completed if
you have a mailing list set up to distribute the group or list in digest
form.  The relevant section of the configuration file explains the
mechanics of this process.

Modtool normally archives the submissions as you approve them, but where
multiple moderators work on one group, this is sometimes undesirable,
since only the posts that you approve will be added to the archive.
Modtool does provide a solution to this problem in that it allows the user
to turn of digest generation when the message is approved, and instead to
create digests by reading approved posts directly from the newsgroup
itself.  The syntax here is

   modtool -d

(or again, a symbolic link to something ending in "digest" will make the
-d implicit).  This should be run at regular intervals (say every day),
and is probably best accomplished using a cron job (type "man crontab" at
a command line for details of how to set this up).  The posts are then
read directly from the newsgroup using NNTP and placed into digests, thus
picking up any posts approved by other moderators.

If you are using a cron job, then you should redirect output to /dev/null,
otherwise you will get lots of messages from root containing the output
from the command.  Doing this will not prevent error messages being
recorded and sent to you in this way.  For example, in my crontab file, I
have 

    27 01 * * * modtool/modtool -d > /dev/null

Advanced configuration file whizzyness
--------------------------------------

By default modtool looks for a configuration file called .modtoolrc, but
it is possible to specify an alternate configuration file on the command
line.  For example, to use the configuration file .mycfg, type

   modtool -f .myfile

In addition, you can specify the a configuration file in the 
MODTOOLRC environment variable, and modtool will use this as the default
configuration file instead.

Modtool looks for configuration files in the current directory, the
same directory as modtool is run from, and the user's home directory, as
well as on an explicit path if you specify one.

If you moderate multiple groups, multiple configuration files are the only
way to use modtool to moderate all of these groups.  You may like to use a
shell script to make your life easier - something like:

    #! /bin/sh
    modtool -f group1
    modtool -f group2
    modtool -f group3

To invoke modtool for each group that you moderate in turn.

Since many of the variables that you use will be duplicated between these
different files, you can use the special command

    include=<filename>

within a config file to cause modtool to read and include the variables
defined in <filename> in addition to those in the current file.  You may
occasionally wish to undefine variables defined in an included file.  To
do this use the statement

    <variable>=

(ie just press return after the equals sign).  Here is a configuration
file that I use for sending out automatic replys. The machine that
receives and processes mail is different to the one that I normally run
modtool on, so a few changes to the configuration are necessary

    # Load in the usual defaults
    include=.modtoolrc

    # Working directory is differently named on this machine
    wd=/aber/ccs95/cot

    # Also requires a different date command
    datecmd=date -u +"%a, %d %h %y %H:%M:%S GMT"

    # Again, this file is stored in a different path on this machine
    arepfile=docs/ack

    # the digest files aren't here, so we disable digests here
    digest=

Hopefully this makes some sort of sense.

Future plans
------------

I don't really have any plans for a modtool 2.1.  Let me know if there is
anything that you think is missing. 

Acknowledgements
----------------

modtool contains code that is based in places upon code snippets provided
by the following people:

  The anonymous author of one of the Perl man pages 
  Thomas Koenig <tkoenig@athena.mit.edu>
  David C. Lawrence <tale@uunet.uu.net>

I'd also like to thank my Mother and Father, without whom this program
would have been impossible to write.

Revision History
----------------

v2.0 - 23rd Oct 1996

 o Several minor bugfixes and efficiency increases.

 o Can create RFC1153 compliant digests from accepted posts, or directly
   from the newsgroup

 o Configuration data is now stored in and read from a separate
   configuration file.

 o can automatically reply to incoming mail when invoked from a mail 
   filtering program.

 o Minor enhancements to save to file feature.

 o Command line help / checking added

v1.1 - 15th Sept 1996

 o No longer requires inews or sendmail, since it can now do mail 
   and news transfers via SMTP and NNTP respectively.

 o Can now cancel posts to your group, should you decide they shouldn't
   be there.

 o Messages no longer have to be processed sequentially. 

 o A rather nasty bug which meant that any moderation mail received whilst
   in modtool was lost has been fixed.

v1.0 - initial release

 o Viewing, Posting, rejection, save to file, Junk features implemented.

Legal Gibberish
---------------

This program 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
of the License, or (at your option) any later version.

This program 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 this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

