  mharc: A web-based mail archiving system

____________________________________________________________________________

    mharc is distributed under the GNU General Public License
    (GPL).  The rules for using and copying mharc are explained in
    the file COPYING.  If you cannot agree to the conditions of the
    GPL but still want to use/copy/distribute the program, you must
    contact the author of mharc, earl@earlhood.com, about arranging
    an alternative license.

____________________________________________________________________________
Table of Contents

  * What is mharc?
  * Installation
  * Archive Customizations
  * Applying Software Updates
  * MH/nmh Support
  * Limitations
  * Author

____________________________________________________________________________
What is mharc?

  It is NOT MHonArc, but it does use MHonArc to do its job.  mharc is
  a collection of Perl and Bourne shell scripts for generating and
  managing web-based searchable archives for mailing lists.  mharc is
  dependent upon the following software:

    Perl, <http://www.perl.com/>
    MHonArc, <http://www.mhonarc.org/>
    Namazu, <http://www.namazu.org/>
    Procmail, <http://www.procmail.org/>

  mharc is distributed under the GNU General Public License.  See
  the file COPYING for specifics.

____________________________________________________________________________
Installation

  NOTE: Please read this entire document before installing and
	configuring mharc since later information may influence what
	you do during the installation and configuration process.

  ____________
  Dependencies

    Perl, MHonArc, Namazu, and Procmail must be installed on your
    system.  To quickly check if you have these packages installed,
    enter the following command at your shell prompt:

      which perl mhonarc namazu procmail

    If the command returns a negative response for some of the
    programs, it does not necessarily indicate that the given program
    is not installed.  It just indicates that is not located in in your
    shell's search path.  Good places to look are in /usr/local/bin
    and /usr/bin.

    If you cannot locate any of the above programs and are not sure
    what is installed on your system, contact your system administrator
    (and while your at it, you may want to ask your sys admin to
    install this software for you :-)

    If you know that a given package is not installed, follow the
    installation instructions for the given package to install it.
    URLs are provided at the beginning of this document on where
    you can download the software.

    The following summarizes the roles that each dependent package
    plays:

      Perl
	  Several mharc scripts are written in the Perl programming
	  language.
      MHonArc
	  MHonArc is used to convert messages into HTML and provide
	  the periodic date and thread indexes.  It also allows
	  customization of archive page layout.
      Namazu
	  Namazu is the search engine.	The reason it is used over
	  others is that it easier to install and use over other
	  alternatives (from the mharc author's perspective).  Plus,
	  it has built-in recognition of MHonArc message pages.
	  Currently, mharc does not support the plugging-in of other
	  search engines.
      Procmail
	  Procmail is used to perform initial message filtering to
	  identify which messages belong to which archives.

  ________________
  Extracting mharc

    After MHonArc, Namazu, and Procmail have been installed, you can
    extract the tar bundle wherever you want to the software installed,
    which you probably already did if your reading this file.  If you
    extracted the bundle into a temporary location, you can re-extract
    to the location you prefer.

    NOTE: Usually, the software is executed by a special user
	  account that is subscribed to the lists that you want
	  archived, and it is recommended to be logged into that
	  account when installing this software.

  _________________
  Configuring mharc

    After you extract the tar bundle, run the command:

      make configure

    Then, you should edit "lib/config.sh" to suit your local settings and
    rerun 'make configure' again to apply your changes.

    NOTE: Make sure to review all variable settings in "lib/config.sh"
	  since proper values are critical for the archiving system
	  to work properly.

    Now, edit "lib/lists.def" to define the mailing lists you want
    archived.  Comments exist in the file describing the syntax of
    the file.  After editing, run the following command:

      make

    This should generate a .procmailrc that will do the initial filtering
    of mail.  At anytime, if you edit "lib/lists.def", you can rerun
    'make' to regenerate the .procmailrc file to reflect your changes.

    The final step is to edit the special user account crontab
    to register the mail archiving scripts to cron inorder to get
    automatic processing of your archives.  The file etc/crontab
    can serve as a template of the crontab entries you should add.
    Generally, you can copy "etc/crontab" verbatim into the crontab for
    the special user account.  Otherwise, you can edit "etc/crontab.in"
    and run 'make configure' to create an "etc/crontab" file suitable
    for copying into your real crontab.

  ______________________
  Maintenance Operations

    Manual maintenance can be done via the Makefile provided.  If you
    run the command,

      make help

    You will get a summary of what targets are available.  Targets exist
    to manually invoke the mail spool processing, to recreate the entire
    HTML archives, and other administrative tasks.

    Some administrative tasks will disable auto-message processing,
    and a message should be displayed when this happens.  You can run

      make enable

    to re-enable auto-message processing.

  ___________________
  Post Install Checks

    * The Perl scripts contained in mharc assume the perl executable
      is located at "/usr/local/bin/perl".  If perl is installed, but
      in a different location, you can create a symbolic link from
      "/usr/local/bin/perl" to the installed location of the perl
      executable.  If you do not have permissions to do this, you will
      need to change the initial #! line in all the Perl scripts to
      reflect the location of perl.

    * mharc calls MHonArc via its library API, therefore make sure
      that the MHonArc library files are located in perl's library
      search path if you chose a different directory to install MHonArc
      library files from perl's site library location.  You may need
      to set the PERL5LIB environment variable to do this.

      NOTE: The 'make configure' command mentioned earlier will
	    automatically check if MHonArc can be loaded.  If not,
	    the command will generate an error message indicating
	    what you can do to fix the problem.

    * Double check the URL to the namazu.cgi program.  A useful
      tip is to copy the namazu.cgi program into the cgi-bin of
      the mharc installation.

    * The file "etc/apache.conf" provides sample configuration
      directives for the Apache HTTP server that may be useful.

    * Make sure your HTTP server allows the execution of CGI
      programs that are denoted with the filename extension ".cgi",
      or specify that cgi-bin directory of the mharc installation 
      is a CGI executable directory.

____________________________________________________________________________
Archive Customizations

  Most of the files that control the appearance of the archive pages
  generated are controled by template files with the extension ".in".
  It is recommended to edit the ".in" version of files and execute the
  'make configure' command to apply your changes.

  NOTE: You must run 'make configure' to have mharc recognize any
	changes you made to a template file.

  The ".in.dist" files are versions of the templates as defined by
  the base distribution.  These will be overwritten when updating
  the software and mainly serve as a starting basis for your custom
  template files.

  The main MHonArc resource file is "lib/common.mrc".  To make
  changes, make edits to "lib/common.mrc.in" and run 'make configure'
  to generate "lib/common.mrc".  You can use "@@VARIABLE_NAME@@"
  references in "lib/common.mrc.in" to refer to variables defined in
  "lib/config.sh".  However, this is normally not required since the
  bin/web-archive program will pre-define various MHonArc resource
  variables that reflect settings in "lib/config.sh".  See the MHonArc
  documentation for more information on how to edit this file.

____________________________________________________________________________
Applying Software Updates

  The software is structured to avoid screwing up an existing
  installation.  All you need to do is extract the newer version
  of the bundle in the same location of the initial installation.
  All the ".in.dist" files will get overwritten, but local ".in"
  files should be left untouched inorder to preserver any local edits.

____________________________________________________________________________
MH/nmh Support

  A program called 'mh-month-pack' is provided with mharc that could
  be used for sites that already have an existing MH/nmh-based mail
  filtering setup (either done manually or automatically).  This
  program could serve as a replacement to the 'filter-spool' step
  for processing incoming messages into the raw archives before
  'web-archive' is invoked.  Run the command,

    mh-month-pack -man

  To view the documentation for mh-month-pack.

____________________________________________________________________________
Limitations

  * The archive search forms rely on some Javascript to pass
    around the Namazu index name since the namazu.cgi program currently
    does provide any namazu template variable for the index name.
    Hopefully, this limitation of namazu will be removed in the future
    so the use of Javascript can be removed.

____________________________________________________________________________
Author

  Earl Hood, earl@earlhood.com

