Updated and edited manpage:

* drop prominent note about being a python program; 
* extended description a bit;
* Document issue with slashes in IMAP mailbox paths.

archivemail.1

@@ -3,7 +3,7 @@
 .\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
 .\" Please send any bug reports, improvements, comments, patches, 
 .\" etc. to Steve Cheng <steve@ggi-project.org>.
-.TH "ARCHIVEMAIL" "1" "03 November 2007" "SP" ""
+.TH "ARCHIVEMAIL" "1" "07 November 2007" "SP" ""
 
 .SH NAME
 archivemail \- archive and compress your old email
@@ -13,18 +13,21 @@ archivemail \- archive and compress your old email
 
 .SH "DESCRIPTION"
 .PP
-\fBarchivemail\fR is a tool written in \fBpython\fR(1) for archiving and
+archivemail is a tool for archiving and compressing old email in mailboxes.
-compressing old email in mailboxes. 
-.PP
 By default it will read the mailbox \fIMAILBOX\fR, moving messages
 that are older that the specified number of days (180 by default) to a
-\fBmbox\fR-format mailbox in the same directory that is compressed
+\fBmbox\fR(5)-format mailbox in the same directory that is compressed
-with \fBgzip\fR(1)\&.  
+with \fBgzip\fR(1)\&.
+It can also just delete old email rather than archive it.
 .PP
 \fBarchivemail\fR supports reading  \fBIMAP\fR,
 \fBMaildir\fR, \fBMH\fR and \fBmbox\fR-format
-mailboxes, but it will always write archive files to \fBmbox\fR-format
+mailboxes, but always writes \fBmbox\fR-format archives.
-mailboxes that are compressed with \fBgzip\fR(1)\&.
+.PP
+Messages that are flagged important are not archived or deleted unless
+explicitely requested with the \fB--include-flagged\fR option.
+Also, \fBarchivemail\fR can be configured not to archive unread mail, or
+to only archive messages larger than a specified size. 
 .PP
 To archive an \fBIMAP\fR-format mailbox, use the format
 \fIimap://username:password@server/mailbox\fR to specify the mailbox. 
@@ -217,7 +220,7 @@ you specify this option, these messages can be archived or deleted just like
 any other message.
 .TP
 \fB    --no-compress\fR
-Do not compress any archives using \fBgzip\fR(1)\&.
+Do not compress any archives.
 .TP
 \fB    --warn-duplicate\fR
 Warn about duplicate \fBMessage-ID\fRs that appear in the input
@@ -296,6 +299,13 @@ You can use a backslash to escape double-quotes that are part of a quoted
 username or password.
 Note that quoting only a substring will not work, and be aware that your shell
 will probably remove unprotected quotes or backslashes. 
+.PP
+\fBIMAP\fR servers supporting subfolders may use any character as a
+mailbox path separator, that is, as an equivalent to the slash character on Unix
+systems. 
+If you are archiving an IMAP subfolder, first \fBarchivemail\fR will try 
+to open a given mailbox name unchanged; if this fails, it will interpret any
+slashes in the URL as path separators and try again. 
 .SH "EXAMPLES"
 .PP
 .PP
@@ -383,18 +393,28 @@ Note the protected quotes.
 .PP
 Probably the best way to run \fBarchivemail\fR is from your \fBcrontab\fR(5)
 file, using the \fB--quiet\fR option.
-.PP
+Don't forget to try the \fB--dry-run\fR and perhaps the
-Don't forget to try the \fB--dry-run\fR option for non-destructive
+\fB--copy\fR option for non-destructive testing.
-testing.
 .SH "EXIT STATUS"
 .PP
 Normally the exit status is 0. Nonzero indicates an unexpected error.
 .SH "BUGS"
 .PP
-There is no support yet for reading \fBMMDF\fR or
+If an \fBIMAP\fR mailbox path contains slashes, the archive filename
-\fBBabyl\fR-format mailboxes. In fact, \fBarchivemail\fR will
+will be derived from the basename of the mailbox. 
-probably think it is reading an \fBmbox\fR-format mailbox and cause
+If the server's folder separator differs from the Unix slash and is used in the
-all sorts of problems.
+\fBIMAP\fR URL, however, the whole path will be considered
+the basename of the mailbox. 
+E.g. the two URLs
+\fBimap://user@example.com/folder/subfolder\fR and
+\fBimap://user@example.com/folder.subfolder\fR will be
+archived in \fIsubfolder_archive.gz\fR and
+\fIfolder.subfolder_archive.gz\fR, respectively, although they
+might refer to the same \fBIMAP\fR mailbox. 
+.PP
+\fBarchivemail\fR does not support reading \fBMMDF\fR or
+\fBBabyl\fR-format mailboxes. In fact, it will probably think it is 
+reading an \fBmbox\fR-format mailbox and cause all sorts of problems.
 .PP
 \fBarchivemail\fR is still too slow, but if you are running from \fBcrontab\fR(5)
 you won't care. Archiving \fBmaildir\fR-format mailboxes should be

archivemail.sgml

@@ -35,7 +35,7 @@
 
 <RefEntry>
 
-<DocInfo><Date>24 October 2007</Date></DocInfo>
+<DocInfo><Date>7 November 2007</Date></DocInfo>
 
 <RefMeta>
 <RefEntryTitle>archivemail</RefEntryTitle>
@@ -62,22 +62,25 @@
 <Title>Description</Title>
 
 <Para>
-<Command/archivemail/ is a tool written in &python; for archiving and
+archivemail is a tool for archiving and compressing old email in mailboxes.
-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
-<application/mbox/-format mailbox in the same directory that is compressed
+&mbox;-format mailbox in the same directory that is compressed
-with &gzip;.  
+with &gzip;.
+It can also just delete old email rather than archive it.
 </Para>
 
 <Para>
 <Command/archivemail/ supports reading  <application/IMAP/,
 <application/Maildir/, <application/MH/ and <application/mbox/-format
-mailboxes, but it will always write archive files to <application/mbox/-format
+mailboxes, but always writes <application/mbox/-format archives.
-mailboxes that are compressed with &gzip;.
+</Para>
+
+<Para>
+    Messages that are flagged important are not archived or deleted unless
+    explicitely requested with the <Option>--include-flagged</Option> option.
+    Also, <command/archivemail/ can be configured not to archive unread mail, or
+    to only archive messages larger than a specified size. 
 </Para>
 
 <Para>
@@ -321,7 +324,7 @@ any other message.
     <Option>--no-compress</Option>
 </Term>
 <ListItem><Para>
-Do not compress any archives using &gzip;.
+Do not compress any archives.
 </Para></ListItem>
 </VarListEntry>
 
@@ -449,6 +452,14 @@ username or password.
 Note that quoting only a substring will not work, and be aware that your shell
 will probably remove unprotected quotes or backslashes. 
 </Para>
+<Para>
+<application/IMAP/ servers supporting subfolders may use any character as a
+mailbox path separator, that is, as an equivalent to the slash character on Unix
+systems. 
+If you are archiving an IMAP subfolder, first <command/archivemail/ will try 
+to open a given mailbox name unchanged; if this fails, it will interpret any
+slashes in the <acronym/URL/ as path separators and try again. 
+</Para>
 </RefSect3>
 </RefSect2>
 
@@ -565,11 +576,8 @@ that are older than 90 days to compressed mailboxes in the
 <Para>
 Probably the best way to run <Command/archivemail/ is from your &crontab;
 file, using the <Option>--quiet</Option> option.
-</Para>
+Don't forget to try the <Option>--dry-run</Option> and perhaps the
-
+<Option>--copy</Option> option for non-destructive testing.
-<Para>
-Don't forget to try the <Option>--dry-run</Option> option for non-destructive
-testing.
 </Para>
 </RefSect1>
 
@@ -582,10 +590,22 @@ testing.
 <RefSect1>
 <Title>Bugs</Title>
 <SimPara>
-There is no support yet for reading <application/MMDF/ or
+If an <application/IMAP/ mailbox path contains slashes, the archive filename
-<application/Babyl/-format mailboxes. In fact, <Command/archivemail/ will
+will be derived from the basename of the mailbox. 
-probably think it is reading an <application/mbox/-format mailbox and cause
+If the server's folder separator differs from the Unix slash and is used in the
-all sorts of problems.
+<application/IMAP/ <acronym/URL/, however, the whole path will be considered
+the basename of the mailbox. 
+E.g. the two <acronym/URL/s
+<userinput>imap://user@example.com/folder/subfolder</userinput> and
+<userinput>imap://user@example.com/folder.subfolder</userinput> will be
+archived in <filename>subfolder_archive.gz</filename> and
+<filename>folder.subfolder_archive.gz</filename>, respectively, although they
+might refer to the same <application/IMAP/ mailbox. 
+</SimPara>
+<SimPara>
+<command/archivemail/ does not support reading <application/MMDF/ or
+<application/Babyl/-format mailboxes. In fact, it will probably think it is 
+reading an <application/mbox/-format mailbox and cause all sorts of problems.
 </SimPara>
 
 <SimPara>