mhonarc-commits
[Top] [All Lists]

CVS: mharc README,1.6,1.7

2002-09-13 18:40:44
Update of /cvsroot/mhonarc/mharc
In directory subversions:/tmp/cvs-serv30435

Modified Files:
	README 
Log Message:
Trimmed up since most information moved to doc/.


Index: README
===================================================================
RCS file: /cvsroot/mhonarc/mharc/README,v
retrieving revision 1.6
retrieving revision 1.7
diff -C2 -r1.6 -r1.7
*** README	12 Mar 2002 22:45:52 -0000	1.6
--- README	14 Sep 2002 01:40:36 -0000	1.7
***************
*** 1,4 ****
!   mharc: A web-based mail archiving system
! 
  ____________________________________________________________________________
  
--- 1,7 ----
! ---------------------------------------------------------------------------
!                           README for mharc
! 	   <http://www.mhonarc.org/release/mharc/latest/>
! 			 Copyright (C) 2002
! 		    Earl Hood, earl(_at_)earlhood(_dot_)com
  ____________________________________________________________________________
  
***************
*** 15,22 ****
    * What is mharc?
    * Installation
!   * Archive Customizations
!   * Applying Software Updates
!   * MH/nmh Support
!   * Limitations
    * Author
  
--- 18,24 ----
    * What is mharc?
    * Installation
!   * Documentation
!   * Mailing List
!   * Version
    * Author
  
***************
*** 24,249 ****
  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.
  
  ____________________________________________________________________________
--- 26,55 ----
  What is mharc?
  
!   mharc is part of the MHonArc Project. mharc is a collection of Perl
!   scripts for generating and managing web-based searchable mailing
!   list archives.
  
  ____________________________________________________________________________
  Installation
+   
+   See the file INSTALL, or better, the HTML version doc/install.html
+   for full installation and configuration instructions.
+ 
+ ____________________________________________________________________________
+ Documentation
+ 
+   Main documentation is kept in HTML format in the doc/ directory.
+   Load doc/index.html into your favorite HTML viewer to get started.
  
! ---------------------------------------------------------------------------
! Mailing List
! 
!   Information about mailing lists, web archives, and other contact
!   information is provided in doc/contacts.html.
! 
! ____________________________________________________________________________
! Version
!   
!   The version of mharc is provided in the file VERSION.
  
  ____________________________________________________________________________
***************
*** 251,253 ****
  
    Earl Hood, earl(_at_)earlhood(_dot_)com
! 
--- 57,59 ----
  
    Earl Hood, earl(_at_)earlhood(_dot_)com
!   $Date$

---------------------------------------------------------------------
To sign-off this list, send email to majordomo(_at_)mhonarc(_dot_)org with the
message text UNSUBSCRIBE MHONARC-DEV