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

on the man page.

8 files changed, 185 insertions, 72 deletions

diff --git a/CHANGELOG b/CHANGELOG
index cfbcb4b..a3924d7 100644
--- a/CHANGELOG
+++ b/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. 
diff --git a/MANIFEST b/MANIFEST
index 0bd13ae..1ff59d2 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -6,5 +6,6 @@ TODO
 archivemail
 archivemail.1
 archivemail.sgml
+examples/archivemail_all
 setup.py
 test_archivemail.py
diff --git a/Makefile b/Makefile
index 7600f49..45a39f3 100644
--- a/Makefile
+++ b/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
diff --git a/README b/README
index 644bd38..8506f62 100644
--- a/README
+++ b/README
@@ -11,10 +11,11 @@ To install archivemail, run:
 
 USE:
 
-'archivemail' is a tool written in Python for organising and storing old
-email choking any of your mailboxes. It can move messages older than a
-certain number of days to a separate 'archive' mbox-format mailbox that
-is compressed with 'gzip'.
+archivemail is a tool written in python(1) for archiving and compressing old
+email in mailboxes. 
+
+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
-archivemail supports, try running 'archivemail --help'.
+'old' is up to you, but the default is 180 days. 
+
+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.
-
-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
-__________________________________________________________________________
+wrong. Check out the 'examples' directory for an example shell script to 
+be run from cron.
 
 The archivemail website is at: http://archivemail.sourceforge.net/
 
diff --git a/archivemail.py b/archivemail.py
index 8feaa1d..4911798 100755
--- a/archivemail.py
+++ b/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
-'mbox' mailbox archives. This is useful for saving space and keeping your
+Moves old mail in mbox, MH or maildir-format mailboxes to an mbox-format
+mailbox compressed with gzip. This is useful for saving space and keeping your
 mailbox manageable.
 
 Options are as follows:
diff --git a/archivemail.sgml b/archivemail.sgml
index 28412fe..c62424f 100644
--- a/archivemail.sgml
+++ b/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/,
-<Replaceable/MH/ and <Replaceable/mbox/-format mailboxes, but it will
-always write archive files in <Replaceable/mbox/-format mailboxes, 
-compressed with &gzip;.
+<Command/archivemail/ supports reading <application/Maildir/,
+<application/MH/ and <application/mbox/-format mailboxes, but it will
+always write archive files to <application/mbox/-format mailboxes that 
+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
-<Command/archivemail/ on a mailbox called `exsouthrock', any archive
-mailbox file will be created with the filename `exsouthrock_archive.gz'.
+mailboxes.  The default is <filename>_archive</filename>. For example, if you
+run <Command/archivemail/ on a mailbox called
+<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.
-</Para></ListItem>
+Warn about duplicate <application/Message-ID/s that appear in the input
+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
-many messages were archived. This should be used if you are running
-<Command/archivemail/ from cron.
+Turns on quiet mode. Do not print any statistics about how many messages were
+archived. This should be used if you are running <Command/archivemail/ from
+cron.
 </Para></ListItem>
 </VarListEntry>
 
@@ -179,42 +192,123 @@ Display brief summary information about how to run <Command/archivemail/.
 <RefSect1>
 <Title>Notes</Title>
 <Para>
+<Command/archivemail/ requires &python; version 2.0 or later.
+</Para>
+
+<Para>
+When reading an <application/mbox/-format mailbox, <command/archivemail/ will
+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.
+last-access and last-modify times of the input mailbox. However, archive
+mailboxes are always created with a mode of <application/0600/.
 </Para>
 
 <Para>
-Probably the best way to run <Command/archivemail/ is from your &crontab;
-file, using the <Option>-q</Option> option.
+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/,
-<Replaceable/Date/ and
-<Replaceable/Resent-Date/.
+<application/Delivery-date/,
+<application/Date/ and
+<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
-<Replaceable/Maildir/ format mailboxes, or the date on the 
-<Replaceable/From/ line on <Replaceable/mbox/-format mailboxes.
+will use the last-modified file timestamp on <application/MH/ and
+<application/Maildir/ format mailboxes, or the date on the 
+<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>
 </RefSect1>
diff --git a/examples/archivemail_all b/examples/archivemail_all
new file mode 100644
index 0000000..30cb05e
--- /dev/null
+++ b/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
diff --git a/setup.py b/setup.py
index 60c27c4..eb50fe6 100755
--- a/setup.py
+++ b/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",