Regenerate manpage from sgml source

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" "30 July 2010" "SP" ""
+.TH "ARCHIVEMAIL" "1" "31 July 2010" "SP" ""
 
 .SH NAME
 archivemail \- archive and compress your old email
@@ -20,6 +20,14 @@ that are older that the specified number of days (180 by default) to a
 with \fBgzip\fR(1)\&.
 It can also just delete old email rather than archive it.
 .PP
+By default, \fBarchivemail\fR derives the archive filename from the
+mailbox name by appending an \fI_archive\fR suffix to the mailbox
+name.  For example, if you run \fBarchivemail\fR on a mailbox called
+\fIexsouthrock\fR, the archive will be created with the
+filename \fIexsouthrock_archive.gz\fR\&.
+This default behavior can be overridden with command line options, choosing
+a custom suffix, a prefix, or a completely custom name for the archive.
+.PP
 \fBarchivemail\fR supports reading  \fBIMAP\fR,
 \fBMaildir\fR, \fBMH\fR and \fBmbox\fR-format
 mailboxes, but always writes \fBmbox\fR-format archives.
@@ -68,17 +76,23 @@ are archiving folders from more than one IMAP account.
 Append \fISTRING\fR to the IMAP filter string. 
 For IMAP wizards. 
 .TP
+\fB    -p \fINAME\fB, --prefix=\fINAME\fB\fR
+Prefix \fINAME\fR to the archive name.
+\fINAME\fR is expanded by the \fBpython\fR(1) function
+\fBtime.strftime()\fR, which means that you can specify special
+directives in \fINAME\fR to make an archive named after the archive
+cut-off date.
+See the discussion of the \fB--suffix\fR option for a list of valid
+\fBstrftime()\fR directives.
+The default is not to add a prefix.
+.TP
 \fB    -s \fINAME\fB, --suffix=\fINAME\fB\fR
 Use the suffix \fINAME\fR to create the filename used for archives.  
-The default is \fI_archive\fR\&. For example, if you
-run \fBarchivemail\fR on a mailbox called
-\fIexsouthrock\fR, the archive will be created
-with the filename \fIexsouthrock_archive.gz\fR\&.
+The default is \fI_archive\fR, unless a prefix is specified.
 
-\fINAME\fR is run through the \fBpython\fR(1) \fBtime.strftime()\fR
-function, which means that you can specify any of the following special
-directives in \fINAME\fR to make archives named after the archive
-cut-off date:
+Like a prefix, the suffix \fINAME\fR is expanded by the \fBpython\fR(1)
+function \fBtime.strftime()\fR with the archive cut-off date.
+\fBtime.strftime()\fR understands the following directives:
 .RS
 .TP 0.2i
 \(bu
@@ -170,6 +184,14 @@ Time zone name (or by no characters if no time zone exists).
 A literal "%" character.
 .RE
 .TP
+\fB    -a \fINAME\fB, --archive-name=\fINAME\fB\fR
+Use \fINAME\fR as the archive name, ignoring the name
+of the mailbox that is archived.
+Like prefixes and suffixes, \fINAME\fR is expanded by
+\fBstrftime()\fR with the archive cut-off date.
+Because it hard-codes the archive name, this option cannot be used when
+archiving multiple mailboxes.
+.TP
 \fB    -S \fINUM\fB, --size=\fINUM\fB\fR
 Only archive messages that are \fINUM\fR bytes or
 greater.
@@ -256,13 +278,13 @@ The archive is locked in the same way when it is updated.
 \fBarchivemail\fR will also complain and abort if a 3rd-party modifies the
 mailbox while it is being read.
 .PP
-\fBarchivemail\fR will always attempt to preserve the mode,
-last-access and last-modify times of the input mailbox. However, archive
+\fBarchivemail\fR will always attempt to preserve the
+last-access and last-modify times of the input mailbox.  Archive
 mailboxes are always created with a mode of \fB0600\fR\&.
 If \fBarchivemail\fR finds a pre-existing archive mailbox it
 will append rather than overwrite that archive.
 \fBarchivemail\fR will refuse to operate on mailboxes that are symbolic 
-links or create tempfiles or archives in world-writable directories.
+links.
 .PP
 \fBarchivemail\fR attempts to find the delivery date of a message by
 looking for valid dates in the following headers, in order of precedence: 
@@ -275,6 +297,14 @@ will use the last-modified file timestamp on \fBMH\fR and
 \fBMaildir\fR format mailboxes, or the date on the 
 \fBFrom\fR line on \fBmbox\fR-format mailboxes.
 .PP
+When archiving mailboxes with leading dots in the name,
+\fBarchivemail\fR will strip the dots off the archive name, so
+that the resulting archive file is not hidden.
+This is not done if the \fB--prefix\fR or
+\fB--archive-name\fR option is used.
+Should there really be mailboxes distinguished only by leading dots in the
+name, they will thus be archived to the same archive file by default.
+.PP
 A conversion from other formats to \fBmbox\fR(5) will silently overwrite existing
 \fBStatus\fR and \fBX-Status\fR message headers. 
 .SS "IMAP"