Added a lot more documentation, fixed up usage messages and expanded a lot

on the man page.

CHANGELOG

@@ -1,3 +1,9 @@
+Version 0.3.1   - 13 April 2002
+  * Added a lot more information to the manpage, including examples and 
+    notes.
+  * Fixed up the README file and archivemail usage message.
+  * Added an example archivemail shell script that I run from crontab.
+
 Version 0.3.1   - 12 April 2002
   * Stopped calling 'gzip' externally and started using the gzip library
     so that we can append to a copy of the gzip archive directly. 

MANIFEST

@@ -6,5 +6,6 @@ TODO
 archivemail
 archivemail.1
 archivemail.sgml
+examples/archivemail_all
 setup.py
 test_archivemail.py

Makefile

@@ -1,11 +1,13 @@
 
-VERSION=0.3.1
+VERSION=0.3.2
+VERSION_TAG=v$(subst .,_,$(VERSION))
+
 
 default:
 	@echo "no default target"
 
 clean:
-	rm -f *.pyc 
+	rm -f *.pyc manpage.links manpage.refs manpage.log
 
 clobber: clean
 	rm -rf build dist
@@ -16,8 +18,18 @@ sdist: clobber
 	rm archivemail
 tag:
 	cvs tag -F current
-	cvs tag v$(VERSION)
+	cvs tag $(VERSION_TAG)
+
+doc: archivemail.1 archivemail.html
 
 archivemail.1: archivemail.sgml
 	nsgmls archivemail.sgml | sgmlspl docbook2man-spec.pl 
 	chmod 644 archivemail.1
+
+archivemail.html: archivemail.sgml
+	jade -t sgml \
+	  -d /usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh/html/docbook.dsl \
+	  -o archivemail.html \
+	  archivemail.sgml
+	mv r1.html archivemail.html
+	chmod 644 archivemail.html

README

@@ -11,10 +11,11 @@ To install archivemail, run:
 
 USE:
 
-'archivemail' is a tool written in Python for organising and storing old
+archivemail is a tool written in python(1) for archiving and compressing old
-email choking any of your mailboxes. It can move messages older than a
+email in mailboxes. 
-certain number of days to a separate 'archive' mbox-format mailbox that
+
-is compressed with 'gzip'.
+It can move messages older than the specified number of days to a separate
+'archive' mbox-format mailbox that is compressed with 'gzip'.
 
 For example, have you been subscribing to the 'linux-kernel' mailing list
 for the last 6 years and ended up with an 160-meg mailbox that 'mutt' is
@@ -24,8 +25,9 @@ just the most recent messages.
 
 'archivemail' can save a lot of disk space and will significantly reduce
 overhead on your mail reader. The number of days before mail is considered
-'old' is up to you, but the default is 180 days. To see the options
+'old' is up to you, but the default is 180 days. 
-archivemail supports, try running 'archivemail --help'.
+
+For more detailed information, look at the archivemail man page.
 
 'archivemail' currently works on mbox, maildir and MH format mailboxes
 and requires python v2.0 or greater. It also supports deleting old mail
@@ -33,41 +35,8 @@ instead of archiving it with the '--delete' option.
 
 The best way to run archivemail is from cron. Giving the '-q' option to
 archivemail will make it quiet, only printing messages if something went 
-wrong.
+wrong. Check out the 'examples' directory for an example shell script to 
-
+be run from cron.
-Another good option to remember is the '--dry-run' or '-n' option, which will
-just show you how many messages it would have archived without actually
-writing to the disk.
-
-archivemail is not exactly blazingly quick at the moment, but if you run it
-from cron you won't mind. Archiving from maildir mailboxes instead of 'mbox'
-is a lot quicker too, since we don't have to do to as much effort to delete
-mail from the original mailbox.
-
-Here is an example script I use for running archivemail from cron:
-__________________________________________________________________________
-
-#!/bin/sh
-#set -x
-set -e
-ARCMAIL="archivemail --output-dir=$HOME/Mail/Archive/ "
-
-$ARCMAIL --days 30 --delete $HOME/Mail/duplicates
-$ARCMAIL --days 90 $HOME/Mail/bugtraq \
-                   $HOME/Mail/debian-devel \
-                   $HOME/Mail/debian-mentors \
-                   $HOME/Mail/debian-user \
-                   $HOME/Mail/jobs \
-                   $HOME/Mail/linux-kernel \
-                   $HOME/Mail/python-list \
-                   $HOME/Mail/spam \
-                   $HOME/Mail/spam-l \
-$ARCMAIL $HOME/Mail/cm-melb \
-         $HOME/Mail/exsouthrock \
-         $HOME/Mail/received \
-         $HOME/Mail/sent \
-         $HOME/Mail/vim
-__________________________________________________________________________
 
 The archivemail website is at: http://archivemail.sourceforge.net/
 

archivemail.py

@@ -22,7 +22,7 @@ Website: http://archivemail.sourceforge.net/
 """
 
 # global administrivia 
-__version__ = "archivemail v0.3.1"
+__version__ = "archivemail v0.3.2"
 __cvs_id__ = "$Id$"
 __copyright__ = """Copyright (C) 2002  Paul Rodger <paul@paulrodger.com>
 This is free software; see the source for copying conditions. There is NO
@@ -476,8 +476,8 @@ def main(args = sys.argv[1:]):
     global _stale
 
     usage = """Usage: %s [options] mailbox [mailbox...]
-Moves old mail messages in mbox or maildir-format mailboxes to gzipped
+Moves old mail in mbox, MH or maildir-format mailboxes to an mbox-format
-'mbox' mailbox archives. This is useful for saving space and keeping your
+mailbox compressed with gzip. This is useful for saving space and keeping your
 mailbox manageable.
 
 Options are as follows:

archivemail.sgml

@@ -1,9 +1,21 @@
 <!DOCTYPE RefEntry PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
 
+<!ENTITY flock "<CiteRefEntry>
+<RefEntryTitle><Command/flock/</RefEntryTitle>
+<ManVolNum/2/</CiteRefEntry>">
+
 <!ENTITY gzip "<CiteRefEntry>
 <RefEntryTitle><Command/gzip/</RefEntryTitle>
 <ManVolNum/1/</CiteRefEntry>">
 
+<!ENTITY mutt "<CiteRefEntry>
+<RefEntryTitle><Command/mutt/</RefEntryTitle>
+<ManVolNum/1/</CiteRefEntry>">
+
+<!ENTITY procmail "<CiteRefEntry>
+<RefEntryTitle><Command/procmail/</RefEntryTitle>
+<ManVolNum/1/</CiteRefEntry>">
+
 <!ENTITY python "<CiteRefEntry>
 <RefEntryTitle><Command/python/</RefEntryTitle>
 <ManVolNum/1/</CiteRefEntry>">
@@ -53,15 +65,15 @@ compressing old email in mailboxes.
 <Para>
 By default it will read the mailbox <Replaceable/MAILBOX/, moving messages
 that are older that the specified number of days (180 by default) to a
-<Replaceable/mbox/-format mailbox in the same directory that is compressed
+<application/mbox/-format mailbox in the same directory that is compressed
 with &gzip;.  
 </Para>
 
 <Para>
-<Command/archivemail/ supports reading <Replaceable/Maildir/,
+<Command/archivemail/ supports reading <application/Maildir/,
-<Replaceable/MH/ and <Replaceable/mbox/-format mailboxes, but it will
+<application/MH/ and <application/mbox/-format mailboxes, but it will
-always write archive files in <Replaceable/mbox/-format mailboxes, 
+always write archive files to <application/mbox/-format mailboxes that 
-compressed with &gzip;.
+are compressed with &gzip;.
 </Para>
 
 <Para>
@@ -101,9 +113,10 @@ read.
 </Term>
 <ListItem><Para>
 Use the suffix <Replaceable/NAME/ to create the filename used for archive
-mailboxes.  The default is `_archive'. For example, if you run
+mailboxes.  The default is <filename>_archive</filename>. For example, if you
-<Command/archivemail/ on a mailbox called `exsouthrock', any archive
+run <Command/archivemail/ on a mailbox called
-mailbox file will be created with the filename `exsouthrock_archive.gz'.
+<filename>exsouthrock</filename>, any archive mailbox file will be created
+with the filename <filename>exsouthrock_archive.gz</filename>.
 </Para></ListItem>
 </VarListEntry>
 
@@ -131,8 +144,8 @@ Delete rather than archive old mail. Use this option with caution!
     <Option>--warn-duplicate</Option>
 </Term>
 <ListItem><Para>
-Warn about duplicate Message-IDs that appear in the input mailbox.
+Warn about duplicate <application/Message-ID/s that appear in the input
-</Para></ListItem>
+mailbox.</Para></ListItem>
 </VarListEntry>
 
 <VarListEntry>
@@ -149,9 +162,9 @@ Reports lots of extra debugging information about what is going on.
     <Option>-q, --quiet</Option>
 </Term>
 <ListItem><Para>
-Turns on <Replaceable/quiet mode/. Do not print any statistics about how
+Turns on quiet mode. Do not print any statistics about how many messages were
-many messages were archived. This should be used if you are running
+archived. This should be used if you are running <Command/archivemail/ from
-<Command/archivemail/ from cron.
+cron.
 </Para></ListItem>
 </VarListEntry>
 
@@ -179,41 +192,122 @@ Display brief summary information about how to run <Command/archivemail/.
 <RefSect1>
 <Title>Notes</Title>
 <Para>
-<Command/archivemail/ will always attempt to preserve the mode,
+<Command/archivemail/ requires &python; version 2.0 or later.
-last-access and last-modify times of the input mailbox.
 </Para>
 
 <Para>
-Probably the best way to run <Command/archivemail/ is from your &crontab;
+When reading an <application/mbox/-format mailbox, <command/archivemail/ will
-file, using the <Option>-q</Option> option.
+create a lockfile with the extension <filename>.lock</filename> so that
+procmail will not deliver to the mailbox while it is being processed. It will
+also create an advisory lock on the mailbox using &flock;.
+</Para>
+
+<Para>
+<Command/archivemail/ will always attempt to preserve the mode,
+last-access and last-modify times of the input mailbox. However, archive
+mailboxes are always created with a mode of <application/0600/.
+</Para>
+
+<Para>
+If <Command/archivemail/ finds a pre-existing archive mailbox it
+will append rather than overwrite that archive.
 </Para>
 
 <Para>
 <Command/archivemail/ attempts to find the delivery date of a message by
 looking for valid dates in the following headers, in order of precedence: 
-<Replaceable/Delivery-date/,
+<application/Delivery-date/,
-<Replaceable/Date/ and
+<application/Date/ and
-<Replaceable/Resent-Date/.
+<application/Resent-Date/.
 If it cannot find any valid date in these headers, it
-will use the last-modified file timestamp on <Replaceable/MH/ and
+will use the last-modified file timestamp on <application/MH/ and
-<Replaceable/Maildir/ format mailboxes, or the date on the 
+<application/Maildir/ format mailboxes, or the date on the 
-<Replaceable/From/ line on <Replaceable/mbox/-format mailboxes.
+<application/From/ line on <application/mbox/-format mailboxes.
+</Para>
+</RefSect1>
+
+<RefSect1>
+<Title>Examples</Title>
+
+<Para>
+To archive all messages in the mailbox <filename>debian-user</filename> that
+are older than 180 days to a compressed mailbox called
+<filename>debian-user_archive.gz</filename> in the current directory: 
+<screen>
+<prompt>bash$ </prompt><userinput>archivemail debian-user</userinput>
+</screen>
+</Para>
+
+<Para>
+To delete all messages in the mailbox <filename>spam</filename> that
+are older than 30 days:
+<screen>
+<prompt>bash$ </prompt><userinput>archivemail --delete --days=30 spam</userinput>
+</screen>
+</Para>
+
+<Para>
+To archive all mailboxes in the directory <filename>$HOME/Mail</filename> 
+that are older than 90 days to compressed mailboxes in the
+<filename>$HOME/Mail/Archive</filename> directory:
+<screen>
+<prompt>bash$ </prompt><userinput>archivemail -d90 -o $HOME/Mail/Archive $HOME/Mail/*</userinput>
+</screen>
+</Para>
+
+</RefSect1>
+
+<RefSect1>
+<Title>Tips</Title>
+<Para>
+Probably the best way to run <Command/archivemail/ is from your &crontab;
+file, using the <Option>--quiet</Option> option.
+</Para>
+
+<Para>
+Don't forget to try the <Option>--dry-run</Option> option for non-destructive
+testing.
 </Para>
 </RefSect1>
 
 <RefSect1>
 <Title>Exit Status</Title>
-<SimPara>Normally the exit status is 0, and nonzero on an unexpected errors.
+<SimPara>Normally the exit status is 0. Nonzero indicates an unexpected error.
+</SimPara>
+</RefSect1>
+
+<RefSect1>
+<Title>Bugs</Title>
+<SimPara>
+There is no support yet for reading <application/MMDF/ or
+<application/Babyl/-format mailboxes. In fact, <Command/archivemail/ will
+probably think it is reading an <application/mbox/-format mailbox and cause
+all sorts of problems.
+</SimPara>
+
+<SimPara>
+<Command/archivemail/ is still too slow, but if you are running from &crontab;
+you won't care. Archiving <application/maildir/-format mailboxes should be
+a lot quicker than <application/mbox/-format mailboxes since it is less
+painful for the original mailbox to be reconstructed after selective message 
+removal.
 </SimPara>
 </RefSect1>
 
 <RefSect1>
 <Title>See Also</Title>
 <SimpleList>
-<Member> &python;, &gzip; </Member>
+<Member> &python;, &gzip;, &mutt;, &procmail;</Member>
 </SimpleList>
 </RefSect1>
 
+<RefSect1>
+<Title>Url</Title>
+<SimPara>The <Command/archivemail/ home page is currently hosted at 
+<ulink type="http" url="http://archivemail.sourceforge.net">sourceforge</ulink>
+</SimPara>
+</RefSect1>
+
 <RefSect1>
 <Title>Author</Title>
 <SimPara>Paul Rodger <Email/paul@paulrodger.com/</SimPara>

examples/archivemail_all

@@ -0,0 +1,31 @@
+#!/bin/sh
+#
+# This is an example shell script I use from my crontab(5) file to selectively
+# archive some of my mailboxes. Most of these mailboxes come directly from 
+# procmail and are in maildir-format -- not that it should really matter.
+#
+# I probably could have done them all as:
+#    $ARCMAIL $HOME/Mail/* 
+# ...if I had enough disk space to keep mail uncompressed for 180 days :)
+#
+set -e
+
+ARCMAIL="/usr/local/bin/archivemail --quiet --output-dir=$HOME/Mail/Archive/ "
+
+$ARCMAIL --days 14 $HOME/Mail/debian-user \
+                   $HOME/Mail/linux-kernel \
+                   $HOME/Mail/python-list \
+                   $HOME/Mail/spam-l
+
+$ARCMAIL --days 30 --delete $HOME/Mail/duplicates
+
+$ARCMAIL --days 90 $HOME/Mail/bugtraq \
+                   $HOME/Mail/debian-devel \
+                   $HOME/Mail/debian-mentors \
+                   $HOME/Mail/spam 
+
+$ARCMAIL $HOME/Mail/cm-melb \
+         $HOME/Mail/exsouthrock \
+         $HOME/Mail/received \
+         $HOME/Mail/sent \
+         $HOME/Mail/vim

setup.py

@@ -20,7 +20,7 @@ check_python_version()  # define & run this early because 'distutils.core' is ne
 from distutils.core import setup
 
 setup(name="archivemail",
-      version="0.3.1",
+      version="0.3.2",
       description="archive and compress old email",
       platforms="POSIX",
       license="GNU GPL",