Added docbook documentation from which we can generate a manpage.

This commit is contained in:
Paul Rodger 2002-04-12 14:46:09 +00:00
parent 5350fc26f6
commit 0203bed0c4
6 changed files with 257 additions and 8 deletions

View File

@ -1,10 +1,10 @@
Version 0.3.1 - ????
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.
* Removed 'bzip2' and 'compress' options since they are increasing
complexity without adding much, and needed to be called externally.
Maybe when we get a bzip2 library I will add back an option to
compression archives using bzip2.
Maybe when python gets a bzip2 library I will add back an option to
compress archives using bzip2.
Version 0.3.0 - 11 April 2002
* We now preserve the last-accessed and last-modified timestamps correctly

View File

@ -4,5 +4,7 @@ MANIFEST
README
TODO
archivemail
archivemail.1
archivemail.sgml
setup.py
test_archivemail.py

22
Makefile Normal file
View File

@ -0,0 +1,22 @@
VERSION=0.3.1
default:
@echo "no default target"
clean:
rm -f *.pyc
clobber: clean
rm -rf build dist
sdist: clobber
cp archivemail.py archivemail
fakeroot python setup.py sdist
rm archivemail
tag:
cvs tag -F current
cvs tag v$(VERSION)
archivemail.1: archivemail.sgml
nsgmls archivemail.sgml | sgmlspl docbook2man-spec.pl

4
README
View File

@ -13,8 +13,8 @@ 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 which
can be compressed with bzip2, gzip or compress.
certain 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

222
archivemail.sgml Normal file
View File

@ -0,0 +1,222 @@
<!DOCTYPE RefEntry PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
<!ENTITY gzip "<CiteRefEntry>
<RefEntryTitle><Command/gzip/</RefEntryTitle>
<ManVolNum/1/</CiteRefEntry>">
<!ENTITY python "<CiteRefEntry>
<RefEntryTitle><Command/python/</RefEntryTitle>
<ManVolNum/1/</CiteRefEntry>">
<!ENTITY seteuid "<CiteRefEntry>
<RefEntryTitle><Command/seteuid/</RefEntryTitle>
<ManVolNum/2/</CiteRefEntry>">
<!ENTITY crontab "<CiteRefEntry>
<RefEntryTitle><Command/crontab/</RefEntryTitle>
<ManVolNum/5/</CiteRefEntry>">
]>
<RefEntry>
<DocInfo><Date>12 April 2002</Date></DocInfo>
<RefMeta>
<RefEntryTitle>archivemail</RefEntryTitle>
<ManVolNum>1</ManVolNum>
<RefMiscInfo>SP</RefMiscInfo>
</RefMeta>
<RefNameDiv>
<RefName>archivemail</RefName>
<RefPurpose>archive and compress your old email</RefPurpose>
</RefNameDiv>
<RefSynopsisDiv>
<CmdSynopsis>
<Command/archivemail/
<Arg><Option>options</Option></Arg>
<Arg choice=req rep=repeat><Replaceable/MAILBOX/</Arg>
</CmdSynopsis>
</RefSynopsisDiv>
<RefSect1>
<Title>Description</Title>
<Para>
<Command/archivemail/ is a tool written in &python; for archiving and
compressing old email in mailboxes.
</Para>
<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
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;.
</Para>
<Para>
<Command/archivemail/ has some support for being run as the root user on
user mailboxes. When running as root, it will &seteuid; to the owner of the
mailbox it is reading, creating any archive files as that user.
</Para>
</RefSect1>
<RefSect1>
<Title>Options</Title>
<VariableList>
<VarListEntry>
<Term>
<Option>-d <Replaceable/NUM/, --days=<Replaceable/NUM/</Option>
</Term>
<ListItem><Para>Archive messages older than <Replaceable/NUM/ days.
The default is 180.
</Para></ListItem>
</VarListEntry>
<VarListEntry>
<Term>
<Option>-o <Replaceable/PATH/, --output-dir=<Replaceable/PATH/</Option>
</Term>
<ListItem><Para>Use the directory name <Replaceable/PATH/ to store the
mailbox archives. The default is the same directory as the mailbox to be
read.
</Para></ListItem>
</VarListEntry>
<VarListEntry>
<Term>
<Option>-s <Replaceable/NAME/, --suffix=<Replaceable/NAME/</Option>
</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'.
</Para></ListItem>
</VarListEntry>
<VarListEntry>
<Term>
<Option>-n, --dry-run</Option>
</Term>
<ListItem><Para>
Don't write to any files -- just show what would have been done. This is
useful for testing to see how many messages would have been archived.
</Para></ListItem>
</VarListEntry>
<VarListEntry>
<Term>
<Option>--delete</Option>
</Term>
<ListItem><Para>
Delete rather than archive old mail. Use this option with caution!
</Para></ListItem>
</VarListEntry>
<VarListEntry>
<Term>
<Option>--warn-duplicate</Option>
</Term>
<ListItem><Para>
Warn about duplicate Message-IDs that appear in the input mailbox.
</Para></ListItem>
</VarListEntry>
<VarListEntry>
<Term>
<Option>-v, --verbose</Option>
</Term>
<ListItem><Para>
Reports lots of extra debugging information about what is going on.
</Para></ListItem>
</VarListEntry>
<VarListEntry>
<Term>
<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.
</Para></ListItem>
</VarListEntry>
<VarListEntry>
<Term>
<Option>-V, --version</Option>
</Term>
<ListItem><Para>
Display the version of <Command/archivemail/ and exit.
</Para></ListItem>
</VarListEntry>
<VarListEntry>
<Term>
<Option>-h, --help</Option>
</Term>
<ListItem><Para>
Display brief summary information about how to run <Command/archivemail/.
</Para></ListItem>
</VarListEntry>
</VariableList>
</RefSect1>
<RefSect1>
<Title>Notes</Title>
<Para>
<Command/archivemail/ will always attempt to preserve the mode,
last-access and last-modify times of the input mailbox.
</Para>
<Para>
Probably the best way to run <Command/archivemail/ is from your &crontab;
file, using the <Option>-q</Option> option.
</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/.
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.
</Para>
</RefSect1>
<RefSect1>
<Title>Exit Status</Title>
<SimPara>Normally the exit status is 0, and nonzero on an unexpected errors.
</SimPara>
</RefSect1>
<RefSect1>
<Title>See Also</Title>
<SimpleList>
<Member> &python;, &gzip; </Member>
</SimpleList>
</RefSect1>
<RefSect1>
<Title>Author</Title>
<SimPara>Paul Rodger <Email/paul@paulrodger.com/</SimPara>
</RefSect1>
</RefEntry>

View File

@ -203,6 +203,7 @@ class TestMboxWrite(unittest.TestCase):
if os.path.exists(name):
os.remove(name)
########## options class testing #################
class TestOptionDefaults(unittest.TestCase):
def testVerbose(self):
@ -222,8 +223,7 @@ class TestOptionDefaults(unittest.TestCase):
self.assertEqual(archivemail.options.quiet, 0)
########## generic routine testing #################
########## archivemail.is_too_old() unit testing #################
class TestIsTooOld(unittest.TestCase):
def testVeryOld(self):
@ -262,6 +262,7 @@ class TestIsTooOld(unittest.TestCase):
time_msg = time.time() + (minutes * 60)
assert(not archivemail.is_too_old(time_message=time_msg, max_days=1))
################ archivemail.choose_temp_dir() unit testing #############
class TestChooseTempDir(unittest.TestCase):
def setUp(self):
@ -460,7 +461,9 @@ class TestArchiveMboxNew(unittest.TestCase):
if os.path.exists(name):
os.remove(name)
#
# Test the file mode (permissions) of the original mailbox after archival
#
class TestArchiveMboxMode(unittest.TestCase):
def setUp(self):
archivemail.options.quiet = 1