diff options
| -rw-r--r-- | MANIFEST.in | 2 | ||||
| -rw-r--r-- | Makefile | 14 | ||||
| -rw-r--r-- | archivemail.1 | 1284 | ||||
| -rw-r--r-- | archivemail.sgml | 715 | ||||
| -rw-r--r-- | archivemail.xml | 718 | ||||
| -rw-r--r-- | db2html.dsl | 40 | ||||
| -rw-r--r-- | db2html.xsl | 11 | ||||
| -rw-r--r-- | manpage.css | 4 |
8 files changed, 1582 insertions, 1206 deletions
diff --git a/MANIFEST.in b/MANIFEST.in index faba49a..f9080f0 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -5,6 +5,6 @@ include MANIFEST include TODO include NEWS include archivemail.1 -include archivemail.sgml +include archivemail.xml graft examples include test_archivemail @@ -4,6 +4,9 @@ VERSION_TAG=v$(subst .,_,$(VERSION)) TARFILE=archivemail-$(VERSION).tar.gz HTDOCS=htdocs-$(VERSION) +# Path to XSLT stylesheet. Adapt to your needs. +XSLT_MAN=/usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl + default: @echo "no default target" @@ -42,13 +45,12 @@ $(HTDOCS).tgz: index.html archivemail.html RELNOTES style.css manpage.css cd $(HTDOCS) && mv archivemail.html manpage.html tar czf $(HTDOCS).tgz $(HTDOCS) -archivemail.1: archivemail.sgml - docbook2man archivemail.sgml - chmod 644 archivemail.1 +archivemail.1: archivemail.xml + xsltproc $(XSLT_MAN) archivemail.xml -archivemail.html: archivemail.sgml db2html.dsl - docbook2html --dsl db2html.dsl -u archivemail.sgml - chmod 644 archivemail.html +archivemail.html: archivemail.xml db2html.xsl + xsltproc --output archivemail.html \ + db2html.xsl archivemail.xml tidy -modify -indent -f /dev/null archivemail.html || true .PHONY: clean test clobber sdist tag upload doc htdocs diff --git a/archivemail.1 b/archivemail.1 index 0daa264..34a13f0 100644 --- a/archivemail.1 +++ b/archivemail.1 @@ -1,486 +1,886 @@ -.\" This manpage has been automatically generated by docbook2man -.\" from a DocBook document. This tool can be found at: -.\" <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" "09 August 2010" "SP" "" - -.SH NAME +'\" t +.\" Title: archivemail +.\" Author: [see the "Author" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/> +.\" Date: 9 August 2010 +.\" Manual: SP +.\" Source: SP +.\" Language: English +.\" +.TH "ARCHIVEMAIL" "1" "9 August 2010" "SP" "SP" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" archivemail \- archive and compress your old email -.SH SYNOPSIS - -\fBarchivemail\fR [ \fBoptions\fR ] \fB\fIMAILBOX\fB\fR\fI ...\fR - +.SH "SYNOPSIS" +.HP \w'\fBarchivemail\fR\ 'u +\fBarchivemail\fR [\fBoptions\fR] {\fIMAILBOX\fR...} .SH "DESCRIPTION" .PP -archivemail is a tool for archiving and compressing old email in mailboxes. -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(5)-format mailbox in the same directory that is compressed -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. -.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. -\fBarchivemail\fR will expand wildcards in \fBIMAP\fR mailbox -names according to RFC 3501, which says: ``The character "*" is a wildcard, and matches zero or more characters at this -position. The character "%" is similar to "*", but it does not match a -hierarchy delimiter.'' -You can omit the password from the URL; use the -\fB--pwfile\fR option to make \fBarchivemail\fR read the -password from a file, or alternatively just enter it upon request. -If the \fB--pwfile\fR option is set, \fBarchivemail\fR does not -look for a password in the URL, and the colon is not considered a -delimiter. -Substitute '\fBimap\fR\&' with '\fBimaps\fR\&', and -\fBarchivemail\fR will establish a secure SSL connection. -See below for more \fBIMAP\fR peculiarities. -.SH "OPTIONS" -.TP -\fB -d \fINUM\fB, --days=\fINUM\fB\fR -Archive messages older than \fINUM\fR days. -The default is 180. This option is incompatible with the -\fB--date\fR option below. -.TP -\fB -D \fIDATE\fB, --date=\fIDATE\fB\fR -Archive messages older than \fIDATE\fR\&. -\fIDATE\fR can be a date string in ISO format (eg '2002-04-23'), -Internet format (eg '23 Apr 2002') or Internet format with full month names -(eg '23 April 2002'). Two-digit years are not supported. -This option is incompatible with the \fB--days\fR option above. -.TP -\fB -o \fIPATH\fB, --output-dir=\fIPATH\fB\fR -Use the directory name \fIPATH\fR to store the -mailbox archives. The default is the same directory as the mailbox to be -read. -.TP -\fB -P \fIFILE\fB, --pwfile=\fIFILE\fB\fR -Read IMAP password from file \fIFILE\fR -instead of from the command line. Note that this will probably not work if you -are archiving folders from more than one IMAP account. -.TP -\fB -F \fISTRING\fB, --filter-append=\fISTRING\fB\fR -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, unless a prefix is specified. +archivemail is a tool for archiving and compressing old email in mailboxes\&. 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(5)\-format mailbox in the same directory that is compressed 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 +_archive +suffix to the mailbox name\&. For example, if you run +\fBarchivemail\fR +on a mailbox called +exsouthrock, the archive will be created with the filename +exsouthrock_archive\&.gz\&. 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 -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 -\fB%a\fR -Locale's abbreviated weekday name. -.TP 0.2i -\(bu -\fB%A\fR -Locale's full weekday name. -.TP 0.2i -\(bu -\fB%b\fR -Locale's abbreviated month name. -.TP 0.2i -\(bu -\fB%B\fR -Locale's full month name. -.TP 0.2i -\(bu -\fB%c\fR -Locale's appropriate date and time representation. -.TP 0.2i -\(bu -\fB%d\fR -Day of the month as a decimal number [01,31]. -.TP 0.2i -\(bu -\fB%H\fR -Hour (24-hour clock) as a decimal number [00,23]. -.TP 0.2i -\(bu -\fB%I\fR -Hour (12-hour clock) as a decimal number [01,12]. -.TP 0.2i -\(bu -\fB%j\fR -Day of the year as a decimal number [001,366]. -.TP 0.2i -\(bu -\fB%m\fR -Month as a decimal number [01,12]. -.TP 0.2i -\(bu -\fB%M\fR -Minute as a decimal number [00,59]. -.TP 0.2i -\(bu -\fB%p\fR -Locale's equivalent of either AM or PM. -.TP 0.2i -\(bu -\fB%S\fR -Second as a decimal number [00,61]. (1) -.TP 0.2i -\(bu -\fB%U\fR -Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0. -.TP 0.2i -\(bu -\fB%w\fR -Weekday as a decimal number [0(Sunday),6]. -.TP 0.2i -\(bu -\fB%W\fR -Week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0. -.TP 0.2i -\(bu -\fB%x\fR -Locale's appropriate date representation. -.TP 0.2i -\(bu -\fB%X\fR -Locale's appropriate time representation. -.TP 0.2i -\(bu -\fB%y\fR -Year without century as a decimal number [00,99]. -.TP 0.2i -\(bu -\fB%Y\fR -Year with century as a decimal number. -.TP 0.2i -\(bu -\fB%Z\fR -Time zone name (or by no characters if no time zone exists). -.TP 0.2i -\(bu -\fB%%\fR -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. -.TP -\fB -n, --dry-run\fR -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. -.TP -\fB -u, --preserve-unread\fR -Do not archive any messages that have not yet been read. \fBarchivemail\fR -determines if a message in a \fBmbox\fR-format or -\fBMH\fR-format mailbox has been read by looking at the -\fBStatus\fR header (if it exists). If the status -header is equal to 'RO' or 'OR' then \fBarchivemail\fR assumes the -message has been read. \fBarchivemail\fR determines if a -\fBmaildir\fR message has -been read by looking at the filename. If the filename contains an 'S' after -\fI:2,\fR then it assumes the message has been read. -.TP -\fB --dont-mangle\fR -Do not mangle lines in message bodies beginning with "From ". When archiving -a message from a mailbox not in \fBmbox\fR format, by default -\fBarchivemail\fR mangles such lines by prepending a '>' to them, since mail -user agents might otherwise interpret these lines as message separators. -Messages from \fBmbox\fR folders are never mangled. See \fBmbox\fR(5) for more -information. -.TP -\fB --delete\fR -Delete rather than archive old mail. Use this option with caution! -.TP -\fB --copy\fR -Copy rather than archive old mail. -Creates an archive, but the archived messages are not deleted from the -originating mailbox, which is left unchanged. -This is a complement to the \fB--delete\fR option, and mainly useful for -testing purposes. -Note that multiple passes will create duplicates, since messages are blindly -appended to an existing archive. -.TP -\fB --all\fR -Archive all messages, without distinction. -.TP -\fB --include-flagged\fR -Normally messages that are flagged important are not archived or deleted. If -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. -.TP -\fB --warn-duplicate\fR -Warn about duplicate \fBMessage-ID\fRs that appear in the input -mailbox. -.TP -\fB -v, --verbose\fR -Reports lots of extra debugging information about what is going on. -.TP -\fB --debug-imap=\fINUM\fB\fR -Set IMAP debugging level. This makes \fBarchivemail\fR dump its -conversation with the IMAP server and some internal IMAP -processing to stdout\&. Higher values for \fINUM\fR give more -elaborate output. Set \fINUM\fR to 4 to see all exchanged -IMAP commands. (Actually, \fINUM\fR is just passed -literally to imaplib.Debug\&.) -.TP -\fB -q, --quiet\fR -Turns on quiet mode. Do not print any statistics about how many messages were -archived. This should be used if you are running \fBarchivemail\fR from -cron. -.TP -\fB -V, --version\fR -Display the version of \fBarchivemail\fR and exit. -.TP -\fB -h, --help\fR -Display brief summary information about how to run \fBarchivemail\fR\&. +\fBarchivemail\fR +supports reading +IMAP, +Maildir, +MH +and +mbox\-format mailboxes, but always writes +mbox\-format archives\&. +.PP +Messages that are flagged important are not archived or deleted unless explicitly 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 +IMAP\-format mailbox, use the format +\fIimap://username:password@server/mailbox \fR +to specify the mailbox\&. +archivemail +will expand wildcards in +IMAP +mailbox names according to +RFC +3501, which says: +\(lq The character "*" is a wildcard, and matches zero or more characters at this position\&. The character "%" is similar to "*", but it does not match a hierarchy delimiter\&.\(rq +You can omit the password from the +URL; use the +\fB\-\-pwfile\fR +option to make +\fBarchivemail\fR +read the password from a file, or alternatively just enter it upon request\&. If the +\fB\-\-pwfile\fR +option is set, +\fBarchivemail\fR +does not look for a password in the +URL, and the colon is not considered a delimiter\&. Substitute \*(Aq\fBimap\fR\*(Aq with \*(Aq\fBimaps\fR\*(Aq, and +\fBarchivemail\fR +will establish a secure +SSL +connection\&. See below for more +IMAP +peculiarities\&. +.SH "OPTIONS" +.PP +\fB\-d \fR\fB\fINUM\fR\fR\fB, \-\-days=\fR\fB\fINUM\fR\fR +.RS 4 +Archive messages older than +\fINUM\fR +days\&. The default is 180\&. This option is incompatible with the +\fB\-\-date\fR +option below\&. +.RE +.PP +\fB\-D \fR\fB\fIDATE\fR\fR\fB, \-\-date=\fR\fB\fIDATE\fR\fR +.RS 4 +Archive messages older than +\fIDATE\fR\&. +\fIDATE\fR +can be a date string in ISO format (eg \*(Aq2002\-04\-23\*(Aq), Internet format (eg \*(Aq23 Apr 2002\*(Aq) or Internet format with full month names (eg \*(Aq23 April 2002\*(Aq)\&. Two\-digit years are not supported\&. This option is incompatible with the +\fB\-\-days\fR +option above\&. +.RE +.PP +\fB\-o \fR\fB\fIPATH\fR\fR\fB, \-\-output\-dir=\fR\fB\fIPATH\fR\fR +.RS 4 +Use the directory name +\fIPATH\fR +to store the mailbox archives\&. The default is the same directory as the mailbox to be read\&. +.RE +.PP +\fB\-P \fR\fB\fIFILE\fR\fR\fB, \-\-pwfile=\fR\fB\fIFILE\fR\fR +.RS 4 +Read +IMAP +password from file +\fIFILE\fR +instead of from the command line\&. Note that this will probably not work if you are archiving folders from more than one IMAP account\&. +.RE +.PP +\fB\-F \fR\fB\fISTRING\fR\fR\fB, \-\-filter\-append=\fR\fB\fISTRING\fR\fR +.RS 4 +Append +\fISTRING\fR +to the +IMAP +filter string\&. For +IMAP +wizards\&. +.RE +.PP +\fB\-p \fR\fB\fINAME\fR\fR\fB, \-\-prefix=\fR\fB\fINAME\fR\fR +.RS 4 +Prefix +\fINAME\fR +to the archive name\&. +\fINAME\fR +is expanded by the +\fBpython\fR(1) +function +time\&.strftime(), 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 +strftime() +directives\&. The default is not to add a prefix\&. +.RE +.PP +\fB\-s \fR\fB\fINAME\fR\fR\fB, \-\-suffix=\fR\fB\fINAME\fR\fR +.RS 4 +Use the suffix +\fINAME\fR +to create the filename used for archives\&. The default is +_archive, unless a prefix is specified\&. +.sp +Like a prefix, the suffix +\fINAME\fR +is expanded by the +\fBpython\fR(1) +function +time\&.strftime() +with the archive cut\-off date\&. +time\&.strftime() +understands the following directives: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%a\fR +Locale\*(Aqs abbreviated weekday name\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%A\fR +Locale\*(Aqs full weekday name\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%b\fR +Locale\*(Aqs abbreviated month name\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%B\fR +Locale\*(Aqs full month name\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%c\fR +Locale\*(Aqs appropriate date and time representation\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%d\fR +Day of the month as a decimal number [01,31]\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%H\fR +Hour (24\-hour clock) as a decimal number [00,23]\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%I\fR +Hour (12\-hour clock) as a decimal number [01,12]\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%j\fR +Day of the year as a decimal number [001,366]\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%m\fR +Month as a decimal number [01,12]\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%M\fR +Minute as a decimal number [00,59]\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%p\fR +Locale\*(Aqs equivalent of either AM or PM\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%S\fR +Second as a decimal number [00,61]\&. (1) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%U\fR +Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]\&. All days in a new year preceding the first Sunday are considered to be in week 0\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%w\fR +Weekday as a decimal number [0(Sunday),6]\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%W\fR +Week number of the year (Monday as the first day of the week) as a decimal number [00,53]\&. All days in a new year preceding the first Sunday are considered to be in week 0\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%x\fR +Locale\*(Aqs appropriate date representation\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%X\fR +Locale\*(Aqs appropriate time representation\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%y\fR +Year without century as a decimal number [00,99]\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%Y\fR +Year with century as a decimal number\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%Z\fR +Time zone name (or by no characters if no time zone exists)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%%\fR +A literal "%" character\&. +.RE +.sp +.RE +.PP +\fB\-a \fR\fB\fINAME\fR\fR\fB, \-\-archive\-name=\fR\fB\fINAME\fR\fR +.RS 4 +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 +strftime() +with the archive cut\-off date\&. Because it hard\-codes the archive name, this option cannot be used when archiving multiple mailboxes\&. +.RE +.PP +\fB\-S \fR\fB\fINUM\fR\fR\fB, \-\-size=\fR\fB\fINUM\fR\fR +.RS 4 +Only archive messages that are +\fINUM\fR +bytes or greater\&. +.RE +.PP +\fB\-n, \-\-dry\-run\fR +.RS 4 +Don\*(Aqt 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\&. +.RE +.PP +\fB\-u, \-\-preserve\-unread\fR +.RS 4 +Do not archive any messages that have not yet been read\&. +\fBarchivemail\fR +determines if a message in a +mbox\-format or +MH\-format mailbox has been read by looking at the +Status +header (if it exists)\&. If the status header is equal to \*(AqRO\*(Aq or \*(AqOR\*(Aq then +archivemail +assumes the message has been read\&. +\fBarchivemail\fR +determines if a +maildir +message has been read by looking at the filename\&. If the filename contains an \*(AqS\*(Aq after +:2, +then it assumes the message has been read\&. +.RE +.PP +\fB\-\-dont\-mangle\fR +.RS 4 +Do not mangle lines in message bodies beginning with "From "\&. When archiving a message from a mailbox not in +mbox +format, by default +\fBarchivemail\fR +mangles such lines by prepending a \*(Aq>\*(Aq to them, since mail user agents might otherwise interpret these lines as message separators\&. Messages from +mbox +folders are never mangled\&. See +\fBmbox\fR(5) +for more information\&. +.RE +.PP +\fB\-\-delete\fR +.RS 4 +Delete rather than archive old mail\&. Use this option with caution! +.RE +.PP +\fB\-\-copy\fR +.RS 4 +Copy rather than archive old mail\&. Creates an archive, but the archived messages are not deleted from the originating mailbox, which is left unchanged\&. This is a complement to the +\fB\-\-delete\fR +option, and mainly useful for testing purposes\&. Note that multiple passes will create duplicates, since messages are blindly appended to an existing archive\&. +.RE +.PP +\fB\-\-all\fR +.RS 4 +Archive all messages, without distinction\&. +.RE +.PP +\fB\-\-include\-flagged\fR +.RS 4 +Normally messages that are flagged important are not archived or deleted\&. If you specify this option, these messages can be archived or deleted just like any other message\&. +.RE +.PP +\fB\-\-no\-compress\fR +.RS 4 +Do not compress any archives\&. +.RE +.PP +\fB\-\-warn\-duplicate\fR +.RS 4 +Warn about duplicate +Message\-IDs that appear in the input mailbox\&. +.RE +.PP +\fB\-v, \-\-verbose\fR +.RS 4 +Reports lots of extra debugging information about what is going on\&. +.RE +.PP +\fB\-\-debug\-imap=\fR\fB\fINUM\fR\fR +.RS 4 +Set +IMAP +debugging level\&. This makes +\fBarchivemail\fR +dump its conversation with the +IMAP +server and some internal +IMAP +processing to +stdout\&. Higher values for +\fINUM\fR +give more elaborate output\&. Set +\fINUM\fR +to 4 to see all exchanged +IMAP +commands\&. (Actually, +\fINUM\fR +is just passed literally to +imaplib\&.Debug\&.) +.RE +.PP +\fB\-q, \-\-quiet\fR +.RS 4 +Turns on quiet mode\&. Do not print any statistics about how many messages were archived\&. This should be used if you are running +\fBarchivemail\fR +from cron\&. +.RE +.PP +\fB\-V, \-\-version\fR +.RS 4 +Display the version of +\fBarchivemail\fR +and exit\&. +.RE +.PP +\fB\-h, \-\-help\fR +.RS 4 +Display brief summary information about how to run +\fBarchivemail\fR\&. +.RE .SH "NOTES" .PP -\fBarchivemail\fR requires \fBpython\fR(1) version 2.3 or later. -When reading an \fBmbox\fR-format mailbox, \fBarchivemail\fR will -create a lockfile with the extension \fI\&.lock\fR 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 \fBlockf\fR(2)\&. -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 -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. -.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: -\fBDelivery-date\fR, -\fBReceived\fR, -\fBResent-Date\fR and -\fBDate\fR\&. -If it cannot find any valid date in these headers, it -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. + +\fBarchivemail\fR +requires +\fBpython\fR(1) +version 2\&.3 or later\&. When reading an +mbox\-format mailbox, +\fBarchivemail\fR +will create a lockfile with the extension +\&.lock +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 +\fBlockf\fR(2)\&. 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 last\-access and last\-modify times of the input mailbox\&. Archive mailboxes are always created with a mode of +0600\&. 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\&. +.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: +Delivery\-date, +Received, +Resent\-Date +and +Date\&. If it cannot find any valid date in these headers, it will use the last\-modified file timestamp on +MH +and +Maildir +format mailboxes, or the date on the +From +line on +mbox\-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. +archivemail +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 +Status +and +X\-Status +message headers\&. .SS "IMAP" .PP -When \fBarchivemail\fR processes an \fBIMAP\fR folder, all messages -in that folder will have their \\Recent flag unset, and they will -probably not show up as 'new' in your user agent later on. -There is no way around this, it's just how \fBIMAP\fR works. -This does not apply, however, if you run \fBarchivemail\fR with the options -\fB--dry-run\fR or \fB--copy\fR\&. -.PP -\fBarchivemail\fR relies on server-side searches to determine the messages -that should be archived. -When matching message dates, \fBIMAP\fR servers refer to server internal -message dates, and these may differ from both delivery time of a message and -its \fBDate\fR header. -Also, there exist broken servers which do not implement server side searches. -.SS "IMAP URLS" -.PP -\fBarchivemail\fR\&'s \fBIMAP\fR URL parser was written -with the RFC 2882 (\fIInternet Message -Format\fR) rules for the local-part of email addresses -in mind. -So, rather than enforcing an URL-style encoding of non-ascii -and reserved characters, it allows to double-quote the username and password. -If your username or password contains the delimiter characters '@' or ':', just -quote it like this: -\fIimap://"username@bogus.com":"password"@imap.bogus.com/mailbox\fR\&. -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 -\fBarchivemail\fR tries to be smart when handling mailbox paths. -In particular, it will automatically add an IMAP NAMESPACE -prefix to the mailbox path if necessary; and if you are archiving a subfolder, -you can use the slash as a path separator instead of the IMAP server's -internal representation. -.SH "EXAMPLES" -.PP +When +\fBarchivemail\fR +processes an +IMAP +folder, all messages in that folder will have their +\eRecent +flag unset, and they will probably not show up as \*(Aqnew\*(Aq in your user agent later on\&. There is no way around this, it\*(Aqs just how +IMAP +works\&. This does not apply, however, if you run +\fBarchivemail\fR +with the options +\fB\-\-dry\-run\fR +or +\fB\-\-copy\fR\&. .PP -To archive all messages in the mailbox \fIdebian-user\fR that -are older than 180 days to a compressed mailbox called -\fIdebian-user_archive.gz\fR in the current directory: -.nf -bash$ \fBarchivemail debian-user\fR -.fi +\fBarchivemail\fR +relies on server\-side searches to determine the messages that should be archived\&. When matching message dates, +IMAP +servers refer to server internal message dates, and these may differ from both delivery time of a message and its +Date +header\&. Also, there exist broken servers which do not implement server side searches\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBIMAP URLS\fR +.RS 4 .PP + +\fBarchivemail\fR\*(Aqs +IMAP +URL +parser was written with the +RFC +2882 (Internet Message Format) rules for the +local\-part +of email addresses in mind\&. So, rather than enforcing an +URL\-style encoding of non\-ascii +and reserved characters, it allows to double\-quote the username and password\&. If your username or password contains the delimiter characters \*(Aq@\*(Aq or \*(Aq:\*(Aq, just quote it like this: +\fIimap://"username@bogus\&.com":"password"@imap\&.bogus\&.com/mailbox \fR\&. 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 -To archive all messages in the mailbox \fIdebian-user\fR that -are older than 180 days to a compressed mailbox called -\fIdebian-user_October_2001.gz\fR (where the current month and -year is April, 2002) in the current directory: +\fBarchivemail\fR +tries to be smart when handling mailbox paths\&. In particular, it will automatically add an +IMAP +NAMESPACE +prefix to the mailbox path if necessary; and if you are archiving a subfolder, you can use the slash as a path separator instead of the +IMAP +server\*(Aqs internal representation\&. +.RE +.SH "EXAMPLES" +.PP +To archive all messages in the mailbox +debian\-user +that are older than 180 days to a compressed mailbox called +debian\-user_archive\&.gz +in the current directory: +.sp +.if n \{\ +.RS 4 +.\} .nf -bash$ \fBarchivemail --suffix '_%B_%Y' debian-user\fR +bash$ \fBarchivemail debian\-user\fR .fi -.PP -.PP -To archive all messages in the mailbox \fIcm-melb\fR that -are older than the first of January 2002 to a compressed mailbox called -\fIcm-melb_archive.gz\fR in the current directory: - +.if n \{\ +.RE +.\} +.PP +To archive all messages in the mailbox +debian\-user +that are older than 180 days to a compressed mailbox called +debian\-user_October_2001\&.gz +(where the current month and year is April, 2002) in the current directory: +.sp +.if n \{\ +.RS 4 +.\} .nf -bash$ \fBarchivemail --date'1 Jan 2002' cm-melb\fR +bash$ \fBarchivemail \-\-suffix \*(Aq_%B_%Y\*(Aq debian\-user\fR .fi -.PP +.if n \{\ +.RE +.\} +.PP +To archive all messages in the mailbox +cm\-melb +that are older than the first of January 2002 to a compressed mailbox called +cm\-melb_archive\&.gz +in the current directory: +.sp +.if n \{\ +.RS 4 +.\} +.nf +bash$ \fBarchivemail \-\-date\*(Aq1 Jan 2002\*(Aq cm\-melb\fR +.fi +.if n \{\ +.RE +.\} .PP Exactly the same as the above example, using an ISO date format instead: - +.sp +.if n \{\ +.RS 4 +.\} .nf -bash$ \fBarchivemail --date=2002-01-01 cm-melb\fR +bash$ \fBarchivemail \-\-date=2002\-01\-01 cm\-melb\fR .fi -.PP -.PP -To delete all messages in the mailbox \fIspam\fR that -are older than 30 days: - +.if n \{\ +.RE +.\} +.PP +To delete all messages in the mailbox +spam +that are older than 30 days: +.sp +.if n \{\ +.RS 4 +.\} .nf -bash$ \fBarchivemail --delete --days=30 spam\fR +bash$ \fBarchivemail \-\-delete \-\-days=30 spam\fR .fi -.PP -.PP -To archive all read messages in the mailbox \fIincoming\fR that -are older than 180 days to a compressed mailbox called -\fIincoming_archive.gz\fR in the current directory: - +.if n \{\ +.RE +.\} +.PP +To archive all read messages in the mailbox +incoming +that are older than 180 days to a compressed mailbox called +incoming_archive\&.gz +in the current directory: +.sp +.if n \{\ +.RS 4 +.\} .nf -bash$ \fBarchivemail --preserve-unread incoming\fR +bash$ \fBarchivemail \-\-preserve\-unread incoming\fR .fi -.PP -.PP -To archive all messages in the mailbox \fIreceived\fR that -are older than 180 days to an uncompressed mailbox called -\fIreceived_archive\fR in the current directory: - +.if n \{\ +.RE +.\} +.PP +To archive all messages in the mailbox +received +that are older than 180 days to an uncompressed mailbox called +received_archive +in the current directory: +.sp +.if n \{\ +.RS 4 +.\} .nf -bash$ \fBarchivemail --no-compress received\fR +bash$ \fBarchivemail \-\-no\-compress received\fR .fi +.if n \{\ +.RE +.\} .PP -.PP -To archive all mailboxes in the directory \fI$HOME/Mail\fR +To archive all mailboxes in the directory +$HOME/Mail that are older than 90 days to compressed mailboxes in the -\fI$HOME/Mail/Archive\fR directory: - +$HOME/Mail/Archive +directory: +.sp +.if n \{\ +.RS 4 +.\} .nf -bash$ \fBarchivemail -d90 -o $HOME/Mail/Archive $HOME/Mail/*\fR +bash$ \fBarchivemail \-d90 \-o $HOME/Mail/Archive $HOME/Mail/*\fR .fi -.PP -.PP -To archive all mails older than 180 days from the given \fBIMAP\fR -INBOX to a compressed mailbox INBOX_archive.gz in the -\fI$HOME/Mail/Archive\fR directory, quoting the password and -reading it from the environment variable \fBPASSWORD\fR: - +.if n \{\ +.RE +.\} +.PP +To archive all mails older than 180 days from the given +IMAP +INBOX to a compressed mailbox INBOX_archive\&.gz in the +$HOME/Mail/Archive +directory, quoting the password and reading it from the environment variable +\fBPASSWORD\fR: +.sp +.if n \{\ +.RS 4 +.\} .nf -bash$ \fBarchivemail -o $HOME/Mail/Archive imaps://user:'"'$PASSWORD'"'@example.org/INBOX\fR +bash$ \fBarchivemail \-o $HOME/Mail/Archive imaps://user:\*(Aq"\*(Aq$PASSWORD\*(Aq"\*(Aq@example\&.org/INBOX\fR .fi -.PP -Note the protected quotes. -.PP -.PP -To archive all mails older than 180 days in subfolders of "foo" on the -given \fBIMAP\fR server to corresponding archives in the current -working directory, reading the password from the file -\fI~/imap-pass.txt\fR: - +.if n \{\ +.RE +.\} +.PP +Note the protected quotes\&. +.PP +To archive all mails older than 180 days in subfolders of "foo" on the given +IMAP +server to corresponding archives in the current working directory, reading the password from the file +~/imap\-pass\&.txt: +.sp +.if n \{\ +.RS 4 +.\} .nf - bash$ \fBarchivemail --pwfile=~/imap-pass.txt imaps://user@example.org/foo/*\fR +bash$ \fBarchivemail \-\-pwfile=~/imap\-pass\&.txt imaps://user@example\&.org/foo/*\fR .fi +.if n \{\ +.RE +.\} .SH "TIPS" .PP -Probably the best way to run \fBarchivemail\fR is from your \fBcrontab\fR(5) -file, using the \fB--quiet\fR option. -Don't forget to try the \fB--dry-run\fR and perhaps the -\fB--copy\fR option for non-destructive testing. +Probably the best way to run +\fBarchivemail\fR +is from your +\fBcrontab\fR(5) +file, using the +\fB\-\-quiet\fR +option\&. Don\*(Aqt forget to try the +\fB\-\-dry\-run\fR +and perhaps the +\fB\-\-copy\fR +option for non\-destructive testing\&. .SH "EXIT STATUS" -.PP -Normally the exit status is 0. Nonzero indicates an unexpected error. +.sp +Normally the exit status is 0\&. Nonzero indicates an unexpected error\&. .SH "BUGS" -.PP -If an \fBIMAP\fR mailbox path contains slashes, the archive filename -will be derived from the basename of the mailbox. -If the server's folder separator differs from the Unix slash and is used in the -\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 -a lot quicker than \fBmbox\fR-format mailboxes since it is less -painful for the original mailbox to be reconstructed after selective message -removal. +.sp +If an IMAP mailbox path contains slashes, the archive filename will be derived from the basename of the mailbox\&. If the server\*(Aqs folder separator differs from the Unix slash and is used in the IMAP 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 subfolder_archive\&.gz and folder\&.subfolder_archive\&.gz, respectively, although they might refer to the same IMAP mailbox\&. +.sp +\fBarchivemail\fR does not support reading MMDF or Babyl\-format mailboxes\&. In fact, it will probably think it is reading an mbox\-format mailbox and cause all sorts of problems\&. +.sp +\fBarchivemail\fR is still too slow, but if you are running from \fBcrontab\fR(5) you won\*(Aqt care\&. Archiving maildir\-format mailboxes should be a lot quicker than mbox\-format mailboxes since it is less painful for the original mailbox to be reconstructed after selective message removal\&. .SH "SEE ALSO" - -\fBpython\fR(1), \fBgzip\fR(1), \fBmutt\fR(1), \fBprocmail\fR(1) +.RS 4 + \fBpython\fR(1), \fBgzip\fR(1), \fBmutt\fR(1), \fBprocmail\fR(1) +.RE .SH "URL" -.PP -The \fBarchivemail\fR home page is currently hosted at -sourceforge <URL:http://archivemail.sourceforge.net> +.sp +The \fBarchivemail\fR home page is currently hosted at \m[blue]\fBsourceforge\fR\m[]\&\s-2\u[1]\d\s+2 .SH "AUTHOR" -.PP -This manual page was written by Paul Rodger <paul at paulrodger dot -com>\&. Updated and supplemented by Nikolaus Schulz -<microschulz@web.de> +.sp +This manual page was written by Paul Rodger <paul at paulrodger dot com>\&. Updated and supplemented by Nikolaus Schulz microschulz@web\&.de +.SH "NOTES" +.IP " 1." 4 +sourceforge +.RS 4 +\%http://archivemail.sourceforge.net +.RE diff --git a/archivemail.sgml b/archivemail.sgml deleted file mode 100644 index 8b227b7..0000000 --- a/archivemail.sgml +++ /dev/null @@ -1,715 +0,0 @@ -<!DOCTYPE RefEntry PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [ - -<!ENTITY lockf "<CiteRefEntry> -<RefEntryTitle><Command/lockf/</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>"> - -<!ENTITY seteuid "<CiteRefEntry> -<RefEntryTitle><Command/seteuid/</RefEntryTitle> -<ManVolNum/2/</CiteRefEntry>"> - -<!ENTITY crontab "<CiteRefEntry> -<RefEntryTitle><Command/crontab/</RefEntryTitle> -<ManVolNum/5/</CiteRefEntry>"> - -<!ENTITY mbox "<CiteRefEntry> -<RefEntryTitle><Command/mbox/</RefEntryTitle> -<ManVolNum/5/</CiteRefEntry>"> -]> - -<RefEntry> - -<DocInfo><Date>9 August 2010</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> -archivemail is a tool for archiving and compressing old email in mailboxes. -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 -&mbox;-format mailbox in the same directory that is compressed -with &gzip;. -It can also just delete old email rather than archive it. -</Para> - -<Para> -By default, <command/archivemail/ derives the archive filename from the -mailbox name by appending an <filename/_archive/ suffix to the mailbox -name. For example, if you run <Command/archivemail/ on a mailbox called -<filename>exsouthrock</filename>, the archive will be created with the -filename <filename>exsouthrock_archive.gz</filename>. -This default behavior can be overridden with command line options, choosing -a custom suffix, a prefix, or a completely custom name for the archive. -</Para> - -<Para> -<Command/archivemail/ supports reading <application/IMAP/, -<application/Maildir/, <application/MH/ and <application/mbox/-format -mailboxes, but always writes <application/mbox/-format archives. -</Para> - -<Para> - Messages that are flagged important are not archived or deleted unless - explicitly 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> -To archive an <application/IMAP/-format mailbox, use the format -<replaceable>imap://username:password@server/mailbox -</replaceable> to specify the mailbox. -<application/archivemail/ will expand wildcards in <application/IMAP/ mailbox -names according to <acronym>RFC</acronym> 3501, which says: <quote> -The character "*" is a wildcard, and matches zero or more characters at this -position. The character "%" is similar to "*", but it does not match a -hierarchy delimiter.</quote> -You can omit the password from the <acronym/URL/; use the -<option>--pwfile</option> option to make <command/archivemail/ read the -password from a file, or alternatively just enter it upon request. -If the <option>--pwfile</option> option is set, <command/archivemail/ does not -look for a password in the <acronym/URL/, and the colon is not considered a -delimiter. -Substitute '<userinput/imap/' with '<userinput/imaps/', and -<command/archivemail/ will establish a secure <acronym/SSL/ connection. -See below for more <application/IMAP/ peculiarities. -</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. This option is incompatible with the -<Option/--date/ option below. -</Para></ListItem> -</VarListEntry> - -<VarListEntry> -<Term> - <Option>-D <Replaceable/DATE/, --date=<Replaceable/DATE/</Option> -</Term> -<ListItem><Para>Archive messages older than <Replaceable/DATE/. -<Replaceable/DATE/ can be a date string in ISO format (eg '2002-04-23'), -Internet format (eg '23 Apr 2002') or Internet format with full month names -(eg '23 April 2002'). Two-digit years are not supported. -This option is incompatible with the <Option/--days/ option above. -</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> -<Term> - <Option>-P <Replaceable/FILE/, --pwfile=<Replaceable/FILE/</Option> -</Term> -<ListItem><Para>Read <acronym/IMAP/ password from file <Replaceable/FILE/ -instead of from the command line. Note that this will probably not work if you -are archiving folders from more than one IMAP account. -</Para></ListItem> -</VarListEntry> - -<VarListEntry> -<Term> - <Option>-F <Replaceable/STRING/, - --filter-append=<Replaceable/STRING/</Option> -</Term> -<ListItem><Para>Append <Replaceable/STRING/ to the <acronym/IMAP/ filter string. -For <acronym/IMAP/ wizards. -</Para></ListItem> -</VarListEntry> - -<VarListEntry> -<Term> - <Option>-p <Replaceable/NAME/, --prefix=<Replaceable/NAME/</Option> -</Term> -<ListItem><Para>Prefix <Replaceable/NAME/ to the archive name. -<Replaceable/NAME/ is expanded by the &python; function -<application/time.strftime()/, which means that you can specify special -directives in <Replaceable/NAME/ to make an archive named after the archive -cut-off date. -See the discussion of the <Option>--suffix</Option> option for a list of valid -<application/strftime()/ directives. -The default is not to add a prefix. -</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 archives. -The default is <filename>_archive</filename>, unless a prefix is specified. -</Para> - -<Para> -Like a prefix, the suffix <Replaceable/NAME/ is expanded by the &python; -function <application/time.strftime()/ with the archive cut-off date. -<application/time.strftime()/ understands the following directives: - -<itemizedlist mark='none'> - <listitem><para><option>%a</option> - Locale's abbreviated weekday name.</para></listitem> - <listitem><para><option>%A</option> - Locale's full weekday name.</para></listitem> - <listitem><para><option>%b</option> - Locale's abbreviated month name.</para></listitem> - <listitem><para><option>%B</option> - Locale's full month name.</para></listitem> - <listitem><para><option>%c</option> - Locale's appropriate date and time representation.</para></listitem> - <listitem><para><option>%d</option> - Day of the month as a decimal number [01,31].</para></listitem> - <listitem><para><option>%H</option> - Hour (24-hour clock) as a decimal number [00,23].</para></listitem> - <listitem><para><option>%I</option> - Hour (12-hour clock) as a decimal number [01,12].</para></listitem> - <listitem><para><option>%j</option> - Day of the year as a decimal number [001,366].</para></listitem> - <listitem><para><option>%m</option> - Month as a decimal number [01,12].</para></listitem> - <listitem><para><option>%M</option> - Minute as a decimal number [00,59].</para></listitem> - <listitem><para><option>%p</option> - Locale's equivalent of either AM or PM.</para></listitem> - <listitem><para><option>%S</option> - Second as a decimal number [00,61]. (1)</para></listitem> - <listitem><para><option>%U</option> - Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0.</para></listitem> - <listitem><para><option>%w</option> - Weekday as a decimal number [0(Sunday),6].</para></listitem> - <listitem><para><option>%W</option> - Week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0.</para></listitem> - <listitem><para><option>%x</option> - Locale's appropriate date representation.</para></listitem> - <listitem><para><option>%X</option> - Locale's appropriate time representation.</para></listitem> - <listitem><para><option>%y</option> - Year without century as a decimal number [00,99].</para></listitem> - <listitem><para><option>%Y</option> - Year with century as a decimal number.</para></listitem> - <listitem><para><option>%Z</option> - Time zone name (or by no characters if no time zone exists).</para></listitem> - <listitem><para><option>%%</option> - A literal "%" character.</para></listitem> -</itemizedlist> - -</Para></ListItem> -</VarListEntry> - -<VarListEntry> -<Term> - <Option>-a <Replaceable/NAME/, --archive-name=<Replaceable/NAME/</Option> -</Term> -<ListItem><Para>Use <Replaceable/NAME/ as the archive name, ignoring the name -of the mailbox that is archived. -Like prefixes and suffixes, <Replaceable/NAME/ is expanded by -<application/strftime()/ with the archive cut-off date. -Because it hard-codes the archive name, this option cannot be used when -archiving multiple mailboxes. -</Para></ListItem> -</VarListEntry> - -<VarListEntry> -<Term> - <Option>-S <Replaceable/NUM/, --size=<Replaceable/NUM/</Option> -</Term> -<ListItem><Para>Only archive messages that are <Replaceable/NUM/ bytes or -greater. -</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>-u, --preserve-unread</Option> -</Term> -<ListItem><Para> -Do not archive any messages that have not yet been read. <command/archivemail/ -determines if a message in a <application/mbox/-format or -<application/MH/-format mailbox has been read by looking at the -<application/Status/ header (if it exists). If the status -header is equal to 'RO' or 'OR' then <application/archivemail/ assumes the -message has been read. <command/archivemail/ determines if a -<application/maildir/ message has -been read by looking at the filename. If the filename contains an 'S' after -<filename>:2,</filename> then it assumes the message has been read. -</Para></ListItem> -</VarListEntry> - -<VarListEntry> -<Term> - <Option>--dont-mangle</Option> -</Term> -<ListItem><Para> -Do not mangle lines in message bodies beginning with "From ". When archiving -a message from a mailbox not in <application/mbox/ format, by default -<command/archivemail/ mangles such lines by prepending a '>' to them, since mail -user agents might otherwise interpret these lines as message separators. -Messages from <application/mbox/ folders are never mangled. See &mbox; for more -information. -</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>--copy</Option> -</Term> -<ListItem><Para> -Copy rather than archive old mail. -Creates an archive, but the archived messages are not deleted from the -originating mailbox, which is left unchanged. -This is a complement to the <option/--delete/ option, and mainly useful for -testing purposes. -Note that multiple passes will create duplicates, since messages are blindly -appended to an existing archive. -</Para></ListItem> -</VarListEntry> - -<VarListEntry> -<Term> - <Option>--all</Option> -</Term> -<ListItem><Para> -Archive all messages, without distinction. -</Para></ListItem> -</VarListEntry> - -<VarListEntry> -<Term> - <Option>--include-flagged</Option> -</Term> -<ListItem><Para> -Normally messages that are flagged important are not archived or deleted. If -you specify this option, these messages can be archived or deleted just like -any other message. -</Para></ListItem> -</VarListEntry> - -<VarListEntry> -<Term> - <Option>--no-compress</Option> -</Term> -<ListItem><Para> -Do not compress any archives. -</Para></ListItem> -</VarListEntry> - -<VarListEntry> -<Term> - <Option>--warn-duplicate</Option> -</Term> -<ListItem><Para> -Warn about duplicate <application/Message-ID/s 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>--debug-imap=<Replaceable/NUM/</Option> -</Term> -<ListItem><Para> -Set <acronym/IMAP/ debugging level. This makes <Command/archivemail/ dump its -conversation with the <acronym/IMAP/ server and some internal <acronym/IMAP/ -processing to <Literal/stdout/. Higher values for <Replaceable/NUM/ give more -elaborate output. Set <Replaceable/NUM/ to 4 to see all exchanged -<acronym/IMAP/ commands. (Actually, <Replaceable/NUM/ is just passed -literally to <Literal/imaplib.Debug/.) -</Para></ListItem> -</VarListEntry> - -<VarListEntry> -<Term> - <Option>-q, --quiet</Option> -</Term> -<ListItem><Para> -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> - -<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/ requires &python; version 2.3 or later. -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 &lockf;. -The archive is locked in the same way when it is updated. -<command/archivemail/ will also complain and abort if a 3rd-party modifies the -mailbox while it is being read. -</Para> - -<Para> -<Command/archivemail/ 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 <application/0600/. -If <Command/archivemail/ finds a pre-existing archive mailbox it -will append rather than overwrite that archive. -<Command/archivemail/ will refuse to operate on mailboxes that are symbolic -links. -</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: -<application/Delivery-date/, -<application/Received/, -<application/Resent-Date/ and -<application/Date/. -If it cannot find any valid date in these headers, it -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> - -<Para> - When archiving mailboxes with leading dots in the name, - <application/archivemail/ will strip the dots off the archive name, so - that the resulting archive file is not hidden. - This is not done if the <Option>--prefix</Option> or - <Option>--archive-name</Option> 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. -</Para> - -<Para> - A conversion from other formats to &mbox; will silently overwrite existing - <application/Status/ and <application/X-Status/ message headers. -</Para> - -<RefSect2> -<Title><acronym/IMAP/</Title> -<Para> -When <command/archivemail/ processes an <application/IMAP/ folder, all messages -in that folder will have their <literal/\Recent/ flag unset, and they will -probably not show up as 'new' in your user agent later on. -There is no way around this, it's just how <application/IMAP/ works. -This does not apply, however, if you run <command/archivemail/ with the options -<option/--dry-run/ or <option/--copy/. -</Para> -<Para> -<command/archivemail/ relies on server-side searches to determine the messages -that should be archived. -When matching message dates, <application/IMAP/ servers refer to server internal -message dates, and these may differ from both delivery time of a message and -its <application/Date/ header. -Also, there exist broken servers which do not implement server side searches. -</Para> -<RefSect3><Title><acronym/IMAP/ <acronym/URLs/</Title> -<Para> -<command/archivemail/'s <application/IMAP/ <acronym/URL/ parser was written -with the <acronym>RFC</acronym> 2882 (<citetitle>Internet Message -Format</citetitle>) rules for the <token>local-part</token> of email addresses -in mind. -So, rather than enforcing an <acronym/URL/-style encoding of non-<acronym/ascii/ -and reserved characters, it allows to double-quote the username and password. -If your username or password contains the delimiter characters '@' or ':', just -quote it like this: -<replaceable>imap://"username@bogus.com":"password"@imap.bogus.com/mailbox -</replaceable>. -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. -</Para> -<Para> -<command/archivemail/ tries to be smart when handling mailbox paths. -In particular, it will automatically add an <acronym/IMAP/ <literal/NAMESPACE/ -prefix to the mailbox path if necessary; and if you are archiving a subfolder, -you can use the slash as a path separator instead of the <acronym/IMAP/ server's -internal representation. -</Para> -</RefSect3> -</RefSect2> - -</RefSect1> - -<RefSect1> -<Title>Examples</Title> - -<InformalExample> -<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> -</InformalExample> - -<InformalExample> -<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_October_2001.gz</filename> (where the current month and -year is April, 2002) in the current directory: -<screen> -<prompt>bash$ </prompt><userinput>archivemail --suffix '_%B_%Y' debian-user</userinput> -</screen> -</Para> -</InformalExample> - -<InformalExample> -<Para> -To archive all messages in the mailbox <filename>cm-melb</filename> that -are older than the first of January 2002 to a compressed mailbox called -<filename>cm-melb_archive.gz</filename> in the current directory: -<screen> -<prompt>bash$ </prompt><userinput>archivemail --date'1 Jan 2002' cm-melb</userinput> -</screen> -</Para> -</InformalExample> - -<InformalExample> -<Para> -Exactly the same as the above example, using an ISO date format instead: -<screen> -<prompt>bash$ </prompt><userinput>archivemail --date=2002-01-01 cm-melb</userinput> -</screen> -</Para> -</InformalExample> - -<InformalExample> -<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> -</InformalExample> - -<InformalExample> -<Para> -To archive all read messages in the mailbox <filename>incoming</filename> that -are older than 180 days to a compressed mailbox called -<filename>incoming_archive.gz</filename> in the current directory: -<screen> -<prompt>bash$ </prompt><userinput>archivemail --preserve-unread incoming</userinput> -</screen> -</Para> -</InformalExample> - -<InformalExample> -<Para> -To archive all messages in the mailbox <filename>received</filename> that -are older than 180 days to an uncompressed mailbox called -<filename>received_archive</filename> in the current directory: -<screen> -<prompt>bash$ </prompt><userinput>archivemail --no-compress received</userinput> -</screen> -</Para> -</InformalExample> - -<InformalExample> -<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> -</InformalExample> - -<InformalExample> -<Para> - To archive all mails older than 180 days from the given <application/IMAP/ - INBOX to a compressed mailbox INBOX_archive.gz in the - <filename>$HOME/Mail/Archive</filename> directory, quoting the password and - reading it from the environment variable <envar>PASSWORD</envar>: -</Para> -<!-- I'm open to suggestions how to avoid making such a super-long line here. --> -<screen> -<prompt>bash$ </prompt><userinput>archivemail -o $HOME/Mail/Archive imaps://user:'"'$PASSWORD'"'@example.org/INBOX</userinput> -</screen> -<Para> - Note the protected quotes. -</Para> -</InformalExample> - -<InformalExample> -<Para> - To archive all mails older than 180 days in subfolders of "foo" on the - given <application/IMAP/ server to corresponding archives in the current - working directory, reading the password from the file - <filename>~/imap-pass.txt</filename>: -</Para> -<screen> - <prompt>bash$ </prompt><userinput>archivemail --pwfile=~/imap-pass.txt imaps://user@example.org/foo/*</userinput> -</screen> -</InformalExample> -</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. -Don't forget to try the <Option>--dry-run</Option> and perhaps the -<Option>--copy</Option> option for non-destructive testing. -</Para> -</RefSect1> - -<RefSect1> -<Title>Exit Status</Title> -<SimPara>Normally the exit status is 0. Nonzero indicates an unexpected error. -</SimPara> -</RefSect1> - -<RefSect1> -<Title>Bugs</Title> -<SimPara> -If an <application/IMAP/ mailbox path contains slashes, the archive filename -will be derived from the basename of the mailbox. -If the server's folder separator differs from the Unix slash and is used in the -<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> -<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;, &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> This manual page was written by Paul Rodger <paul at paulrodger dot -com>. Updated and supplemented by Nikolaus Schulz -<email>microschulz@web.de</email></SimPara> -</RefSect1> - -</RefEntry> diff --git a/archivemail.xml b/archivemail.xml new file mode 100644 index 0000000..6542351 --- /dev/null +++ b/archivemail.xml @@ -0,0 +1,718 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"file:///usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd" [ + +<!ENTITY lockf "<citerefentry> +<refentrytitle><command>lockf</command></refentrytitle> +<manvolnum>2</manvolnum></citerefentry>"> + +<!ENTITY gzip "<citerefentry> +<refentrytitle><command>gzip</command></refentrytitle> +<manvolnum>1</manvolnum></citerefentry>"> + +<!ENTITY mutt "<citerefentry> +<refentrytitle><command>mutt</command></refentrytitle> +<manvolnum>1</manvolnum></citerefentry>"> + +<!ENTITY procmail "<citerefentry> +<refentrytitle><command>procmail</command></refentrytitle> +<manvolnum>1</manvolnum></citerefentry>"> + +<!ENTITY python "<citerefentry> +<refentrytitle><command>python</command></refentrytitle> +<manvolnum>1</manvolnum></citerefentry>"> + +<!ENTITY seteuid "<citerefentry> +<refentrytitle><command>seteuid</command></refentrytitle> +<manvolnum>2</manvolnum></citerefentry>"> + +<!ENTITY crontab "<citerefentry> +<refentrytitle><command>crontab</command></refentrytitle> +<manvolnum>5</manvolnum></citerefentry>"> + +<!ENTITY mbox "<citerefentry> +<refentrytitle><command>mbox</command></refentrytitle> +<manvolnum>5</manvolnum></citerefentry>"> +]> + +<refentry> + +<docinfo><date>9 August 2010</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</command> +<arg><option>options</option></arg> +<arg choice="req" rep="repeat"><replaceable>MAILBOX</replaceable></arg> + +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para> +archivemail is a tool for archiving and compressing old email in mailboxes. +By default it will read the mailbox <replaceable>MAILBOX</replaceable>, moving messages +that are older that the specified number of days (180 by default) to a +&mbox;-format mailbox in the same directory that is compressed +with &gzip;. +It can also just delete old email rather than archive it. +</para> + +<para> +By default, <command>archivemail</command> derives the archive filename from the +mailbox name by appending an <filename>_archive</filename> suffix to the mailbox +name. For example, if you run <command>archivemail</command> on a mailbox called +<filename>exsouthrock</filename>, the archive will be created with the +filename <filename>exsouthrock_archive.gz</filename>. +This default behavior can be overridden with command line options, choosing +a custom suffix, a prefix, or a completely custom name for the archive. +</para> + +<para> +<command>archivemail</command> supports reading <application>IMAP</application>, +<application>Maildir</application>, <application>MH</application> and <application>mbox</application>-format +mailboxes, but always writes <application>mbox</application>-format archives. +</para> + +<para> + Messages that are flagged important are not archived or deleted unless + explicitly requested with the <option>--include-flagged</option> option. + Also, <command>archivemail</command> can be configured not to archive unread mail, or + to only archive messages larger than a specified size. +</para> + +<para> +To archive an <application>IMAP</application>-format mailbox, use the format +<replaceable>imap://username:password@server/mailbox +</replaceable> to specify the mailbox. +<application>archivemail</application> will expand wildcards in <application>IMAP</application> mailbox +names according to <acronym>RFC</acronym> 3501, which says: <quote> +The character "*" is a wildcard, and matches zero or more characters at this +position. The character "%" is similar to "*", but it does not match a +hierarchy delimiter.</quote> +You can omit the password from the <acronym>URL</acronym>; use the +<option>--pwfile</option> option to make <command>archivemail</command> read the +password from a file, or alternatively just enter it upon request. +If the <option>--pwfile</option> option is set, <command>archivemail</command> does not +look for a password in the <acronym>URL</acronym>, and the colon is not considered a +delimiter. +Substitute '<userinput>imap</userinput>' with '<userinput>imaps</userinput>', and +<command>archivemail</command> will establish a secure <acronym>SSL</acronym> connection. +See below for more <application>IMAP</application> peculiarities. +</para> +</refsect1> + +<refsect1> +<title>Options</title> + +<variablelist> + +<varlistentry> +<term> + <option>-d <replaceable>NUM</replaceable>, --days=<replaceable>NUM</replaceable></option> +</term> +<listitem><para>Archive messages older than <replaceable>NUM</replaceable> days. +The default is 180. This option is incompatible with the +<option>--date</option> option below. +</para></listitem> +</varlistentry> + +<varlistentry> +<term> + <option>-D <replaceable>DATE</replaceable>, --date=<replaceable>DATE</replaceable></option> +</term> +<listitem><para>Archive messages older than <replaceable>DATE</replaceable>. +<replaceable>DATE</replaceable> can be a date string in ISO format (eg '2002-04-23'), +Internet format (eg '23 Apr 2002') or Internet format with full month names +(eg '23 April 2002'). Two-digit years are not supported. +This option is incompatible with the <option>--days</option> option above. +</para></listitem> +</varlistentry> + +<varlistentry> +<term> + <option>-o <replaceable>PATH</replaceable>, --output-dir=<replaceable>PATH</replaceable></option> +</term> +<listitem><para>Use the directory name <replaceable>PATH</replaceable> to store the +mailbox archives. The default is the same directory as the mailbox to be +read. +</para></listitem> +</varlistentry> + +<varlistentry> +<term> + <option>-P <replaceable>FILE</replaceable>, --pwfile=<replaceable>FILE</replaceable></option> +</term> +<listitem><para>Read <acronym>IMAP</acronym> password from file <replaceable>FILE</replaceable> +instead of from the command line. Note that this will probably not work if you +are archiving folders from more than one IMAP account. +</para></listitem> +</varlistentry> + +<varlistentry> +<term> + <option>-F <replaceable>STRING</replaceable>, + --filter-append=<replaceable>STRING</replaceable></option> +</term> +<listitem><para>Append <replaceable>STRING</replaceable> to the <acronym>IMAP</acronym> filter string. +For <acronym>IMAP</acronym> wizards. +</para></listitem> +</varlistentry> + +<varlistentry> +<term> + <option>-p <replaceable>NAME</replaceable>, --prefix=<replaceable>NAME</replaceable></option> +</term> +<listitem><para>Prefix <replaceable>NAME</replaceable> to the archive name. +<replaceable>NAME</replaceable> is expanded by the &python; function +<application>time.strftime()</application>, which means that you can specify special +directives in <replaceable>NAME</replaceable> to make an archive named after the archive +cut-off date. +See the discussion of the <option>--suffix</option> option for a list of valid +<application>strftime()</application> directives. +The default is not to add a prefix. +</para></listitem> +</varlistentry> + +<varlistentry> +<term> + <option>-s <replaceable>NAME</replaceable>, --suffix=<replaceable>NAME</replaceable></option> +</term> +<listitem><para> +Use the suffix <replaceable>NAME</replaceable> to create the filename used for archives. +The default is <filename>_archive</filename>, unless a prefix is specified. +</para> + +<para> +Like a prefix, the suffix <replaceable>NAME</replaceable> is expanded by the &python; +function <application>time.strftime()</application> with the archive cut-off date. +<application>time.strftime()</application> understands the following directives: + +<itemizedlist mark='none'> + <listitem><para><option>%a</option> + Locale's abbreviated weekday name.</para></listitem> + <listitem><para><option>%A</option> + Locale's full weekday name.</para></listitem> + <listitem><para><option>%b</option> + Locale's abbreviated month name.</para></listitem> + <listitem><para><option>%B</option> + Locale's full month name.</para></listitem> + <listitem><para><option>%c</option> + Locale's appropriate date and time representation.</para></listitem> + <listitem><para><option>%d</option> + Day of the month as a decimal number [01,31].</para></listitem> + <listitem><para><option>%H</option> + Hour (24-hour clock) as a decimal number [00,23].</para></listitem> + <listitem><para><option>%I</option> + Hour (12-hour clock) as a decimal number [01,12].</para></listitem> + <listitem><para><option>%j</option> + Day of the year as a decimal number [001,366].</para></listitem> + <listitem><para><option>%m</option> + Month as a decimal number [01,12].</para></listitem> + <listitem><para><option>%M</option> + Minute as a decimal number [00,59].</para></listitem> + <listitem><para><option>%p</option> + Locale's equivalent of either AM or PM.</para></listitem> + <listitem><para><option>%S</option> + Second as a decimal number [00,61]. (1)</para></listitem> + <listitem><para><option>%U</option> + Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0.</para></listitem> + <listitem><para><option>%w</option> + Weekday as a decimal number [0(Sunday),6].</para></listitem> + <listitem><para><option>%W</option> + Week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0.</para></listitem> + <listitem><para><option>%x</option> + Locale's appropriate date representation.</para></listitem> + <listitem><para><option>%X</option> + Locale's appropriate time representation.</para></listitem> + <listitem><para><option>%y</option> + Year without century as a decimal number [00,99].</para></listitem> + <listitem><para><option>%Y</option> + Year with century as a decimal number.</para></listitem> + <listitem><para><option>%Z</option> + Time zone name (or by no characters if no time zone exists).</para></listitem> + <listitem><para><option>%%</option> + A literal "%" character.</para></listitem> +</itemizedlist> + +</para></listitem> +</varlistentry> + +<varlistentry> +<term> + <option>-a <replaceable>NAME</replaceable>, --archive-name=<replaceable>NAME</replaceable></option> +</term> +<listitem><para>Use <replaceable>NAME</replaceable> as the archive name, ignoring the name +of the mailbox that is archived. +Like prefixes and suffixes, <replaceable>NAME</replaceable> is expanded by +<application>strftime()</application> with the archive cut-off date. +Because it hard-codes the archive name, this option cannot be used when +archiving multiple mailboxes. +</para></listitem> +</varlistentry> + +<varlistentry> +<term> + <option>-S <replaceable>NUM</replaceable>, --size=<replaceable>NUM</replaceable></option> +</term> +<listitem><para>Only archive messages that are <replaceable>NUM</replaceable> bytes or +greater. +</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>-u, --preserve-unread</option> +</term> +<listitem><para> +Do not archive any messages that have not yet been read. <command>archivemail</command> +determines if a message in a <application>mbox</application>-format or +<application>MH</application>-format mailbox has been read by looking at the +<application>Status</application> header (if it exists). If the status +header is equal to 'RO' or 'OR' then <application>archivemail</application> assumes the +message has been read. <command>archivemail</command> determines if a +<application>maildir</application> message has +been read by looking at the filename. If the filename contains an 'S' after +<filename>:2,</filename> then it assumes the message has been read. +</para></listitem> +</varlistentry> + +<varlistentry> +<term> + <option>--dont-mangle</option> +</term> +<listitem><para> +Do not mangle lines in message bodies beginning with "From ". When archiving +a message from a mailbox not in <application>mbox</application> format, by default +<command>archivemail</command> mangles such lines by prepending a '>' to them, since mail +user agents might otherwise interpret these lines as message separators. +Messages from <application>mbox</application> folders are never mangled. See &mbox; for more +information. +</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>--copy</option> +</term> +<listitem><para> +Copy rather than archive old mail. +Creates an archive, but the archived messages are not deleted from the +originating mailbox, which is left unchanged. +This is a complement to the <option>--delete</option> option, and mainly useful for +testing purposes. +Note that multiple passes will create duplicates, since messages are blindly +appended to an existing archive. +</para></listitem> +</varlistentry> + +<varlistentry> +<term> + <option>--all</option> +</term> +<listitem><para> +Archive all messages, without distinction. +</para></listitem> +</varlistentry> + +<varlistentry> +<term> + <option>--include-flagged</option> +</term> +<listitem><para> +Normally messages that are flagged important are not archived or deleted. If +you specify this option, these messages can be archived or deleted just like +any other message. +</para></listitem> +</varlistentry> + +<varlistentry> +<term> + <option>--no-compress</option> +</term> +<listitem><para> +Do not compress any archives. +</para></listitem> +</varlistentry> + +<varlistentry> +<term> + <option>--warn-duplicate</option> +</term> +<listitem><para> +Warn about duplicate <application>Message-ID</application>s 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>--debug-imap=<replaceable>NUM</replaceable></option> +</term> +<listitem><para> +Set <acronym>IMAP</acronym> debugging level. This makes <command>archivemail</command> dump its +conversation with the <acronym>IMAP</acronym> server and some internal <acronym>IMAP</acronym> +processing to <literal>stdout</literal>. Higher values for <replaceable>NUM</replaceable> give more +elaborate output. Set <replaceable>NUM</replaceable> to 4 to see all exchanged +<acronym>IMAP</acronym> commands. (Actually, <replaceable>NUM</replaceable> is just passed +literally to <literal>imaplib.Debug</literal>.) +</para></listitem> +</varlistentry> + +<varlistentry> +<term> + <option>-q, --quiet</option> +</term> +<listitem><para> +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</command> from +cron. +</para></listitem> +</varlistentry> + +<varlistentry> +<term> + <option>-V, --version</option> +</term> +<listitem><para> +Display the version of <command>archivemail</command> and exit. +</para></listitem> +</varlistentry> + +<varlistentry> +<term> + <option>-h, --help</option> +</term> +<listitem><para> +Display brief summary information about how to run <command>archivemail</command>. +</para></listitem> +</varlistentry> +</variablelist> + +</refsect1> + +<refsect1> +<title>Notes</title> +<para> +<command>archivemail</command> requires &python; version 2.3 or later. +When reading an <application>mbox</application>-format mailbox, <command>archivemail</command> 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 &lockf;. +The archive is locked in the same way when it is updated. +<command>archivemail</command> will also complain and abort if a 3rd-party modifies the +mailbox while it is being read. +</para> + +<para> +<command>archivemail</command> 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 <application>0600</application>. +If <command>archivemail</command> finds a pre-existing archive mailbox it +will append rather than overwrite that archive. +<command>archivemail</command> will refuse to operate on mailboxes that are symbolic +links. +</para> + +<para> +<command>archivemail</command> attempts to find the delivery date of a message by +looking for valid dates in the following headers, in order of precedence: +<application>Delivery-date</application>, +<application>Received</application>, +<application>Resent-Date</application> and +<application>Date</application>. +If it cannot find any valid date in these headers, it +will use the last-modified file timestamp on <application>MH</application> and +<application>Maildir</application> format mailboxes, or the date on the +<application>From</application> line on <application>mbox</application>-format mailboxes. +</para> + +<para> + When archiving mailboxes with leading dots in the name, + <application>archivemail</application> will strip the dots off the archive name, so + that the resulting archive file is not hidden. + This is not done if the <option>--prefix</option> or + <option>--archive-name</option> 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. +</para> + +<para> + A conversion from other formats to &mbox; will silently overwrite existing + <application>Status</application> and <application>X-Status</application> message headers. +</para> + +<refsect2> +<title><acronym>IMAP</acronym></title> +<para> +When <command>archivemail</command> processes an <application>IMAP</application> folder, all messages +in that folder will have their <literal>\Recent</literal> flag unset, and they will +probably not show up as 'new' in your user agent later on. +There is no way around this, it's just how <application>IMAP</application> works. +This does not apply, however, if you run <command>archivemail</command> with the options +<option>--dry-run</option> or <option>--copy</option>. +</para> +<para> +<command>archivemail</command> relies on server-side searches to determine the messages +that should be archived. +When matching message dates, <application>IMAP</application> servers refer to server internal +message dates, and these may differ from both delivery time of a message and +its <application>Date</application> header. +Also, there exist broken servers which do not implement server side searches. +</para> +<refsect3><title><acronym>IMAP</acronym> <acronym>URLS</acronym></title> +<para> +<command>archivemail</command>'s <application>IMAP</application> <acronym>URL</acronym> parser was written +with the <acronym>RFC</acronym> 2882 (<citetitle>Internet Message +Format</citetitle>) rules for the <token>local-part</token> of email addresses +in mind. +So, rather than enforcing an <acronym>URL</acronym>-style encoding of non-<acronym>ascii</acronym> +and reserved characters, it allows to double-quote the username and password. +If your username or password contains the delimiter characters '@' or ':', just +quote it like this: +<replaceable>imap://"username@bogus.com":"password"@imap.bogus.com/mailbox +</replaceable>. +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. +</para> +<para> +<command>archivemail</command> tries to be smart when handling mailbox paths. +In particular, it will automatically add an <acronym>IMAP</acronym> <literal>NAMESPACE</literal> +prefix to the mailbox path if necessary; and if you are archiving a subfolder, +you can use the slash as a path separator instead of the <acronym>IMAP</acronym> server's +internal representation. +</para> +</refsect3> +</refsect2> + +</refsect1> + +<refsect1> +<title>Examples</title> + +<informalexample> +<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> +</informalexample> + +<informalexample> +<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_October_2001.gz</filename> (where the current month and +year is April, 2002) in the current directory: +<screen> +<prompt>bash$ </prompt><userinput>archivemail --suffix '_%B_%Y' debian-user</userinput> +</screen> +</para> +</informalexample> + +<informalexample> +<para> +To archive all messages in the mailbox <filename>cm-melb</filename> that +are older than the first of January 2002 to a compressed mailbox called +<filename>cm-melb_archive.gz</filename> in the current directory: +<screen> +<prompt>bash$ </prompt><userinput>archivemail --date'1 Jan 2002' cm-melb</userinput> +</screen> +</para> +</informalexample> + +<informalexample> +<para> +Exactly the same as the above example, using an ISO date format instead: +<screen> +<prompt>bash$ </prompt><userinput>archivemail --date=2002-01-01 cm-melb</userinput> +</screen> +</para> +</informalexample> + +<informalexample> +<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> +</informalexample> + +<informalexample> +<para> +To archive all read messages in the mailbox <filename>incoming</filename> that +are older than 180 days to a compressed mailbox called +<filename>incoming_archive.gz</filename> in the current directory: +<screen> +<prompt>bash$ </prompt><userinput>archivemail --preserve-unread incoming</userinput> +</screen> +</para> +</informalexample> + +<informalexample> +<para> +To archive all messages in the mailbox <filename>received</filename> that +are older than 180 days to an uncompressed mailbox called +<filename>received_archive</filename> in the current directory: +<screen> +<prompt>bash$ </prompt><userinput>archivemail --no-compress received</userinput> +</screen> +</para> +</informalexample> + +<informalexample> +<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> +</informalexample> + +<informalexample> +<para> + To archive all mails older than 180 days from the given <application>IMAP</application> + INBOX to a compressed mailbox INBOX_archive.gz in the + <filename>$HOME/Mail/Archive</filename> directory, quoting the password and + reading it from the environment variable <envar>PASSWORD</envar>: +</para> +<!-- i'm open to suggestions how to avoid making such a super-long line here. --> +<screen> +<prompt>bash$ </prompt><userinput>archivemail -o $HOME/Mail/Archive imaps://user:'"'$PASSWORD'"'@example.org/INBOX</userinput> +</screen> +<para> + Note the protected quotes. +</para> +</informalexample> + +<informalexample> +<para> + To archive all mails older than 180 days in subfolders of "foo" on the + given <application>IMAP</application> server to corresponding archives in the current + working directory, reading the password from the file + <filename>~/imap-pass.txt</filename>: +</para> +<screen> +<prompt>bash$ </prompt><userinput>archivemail --pwfile=~/imap-pass.txt imaps://user@example.org/foo/*</userinput> +</screen> +</informalexample> +</refsect1> + +<refsect1> +<title>Tips</title> +<para> +Probably the best way to run <command>archivemail</command> is from your &crontab; +file, using the <option>--quiet</option> option. +Don't forget to try the <option>--dry-run</option> and perhaps the +<option>--copy</option> option for non-destructive testing. +</para> +</refsect1> + +<refsect1> +<title>Exit Status</title> +<simpara>Normally the exit status is 0. Nonzero indicates an unexpected error. +</simpara> +</refsect1> + +<refsect1> +<title>Bugs</title> +<simpara> +If an <application>IMAP</application> mailbox path contains slashes, the archive filename +will be derived from the basename of the mailbox. +If the server's folder separator differs from the Unix slash and is used in the +<application>IMAP</application> <acronym>URL</acronym>, however, the whole path will be considered +the basename of the mailbox. +E.g. the two <acronym>URL</acronym>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</application> mailbox. +</simpara> +<simpara> +<command>archivemail</command> does not support reading <application>MMDF</application> or +<application>Babyl</application>-format mailboxes. In fact, it will probably think it is +reading an <application>mbox</application>-format mailbox and cause all sorts of problems. +</simpara> + +<simpara> +<command>archivemail</command> is still too slow, but if you are running from &crontab; +you won't care. Archiving <application>maildir</application>-format mailboxes should be +a lot quicker than <application>mbox</application>-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;, &mutt;, &procmail;</member> +</simplelist> +</refsect1> + +<refsect1> +<title>Url</title> +<simpara>The <command>archivemail</command> home page is currently hosted at +<ulink type="http" url="http://archivemail.sourceforge.net">sourceforge</ulink> +</simpara> +</refsect1> + +<refsect1> +<title>Author</title> +<simpara> This manual page was written by Paul Rodger <paul at paulrodger dot +com>. Updated and supplemented by Nikolaus Schulz +<email>microschulz@web.de</email></simpara> +</refsect1> + +</refentry> diff --git a/db2html.dsl b/db2html.dsl deleted file mode 100644 index cac5775..0000000 --- a/db2html.dsl +++ /dev/null @@ -1,40 +0,0 @@ -<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [ - -<!ENTITY dbstyle SYSTEM "/usr/share/sgml/docbook/stylesheet/dsssl/modular/html/docbook.dsl" CDATA DSSSL> -]> - -<style-sheet> -<style-specification use="docbook"> -<style-specification-body> - -(define %css-decoration% - ; Enable html element decoration with 'style=...' css? -#t) - -(define %stylesheet% - ; Needed if we want to use a css file -"manpage.css") - -(define %shade-verbatim% - ;; Should verbatim environments be shaded? - #t) - -; Override $refentry-body$ from dbrfntry.dsl -; to add a hr after the refentry title h1. -(define ($refentry-body$) - (let ((id (element-id (current-node)))) - (make sequence - (make element gi: "H1" - (make sequence - (make element gi: "A" - attributes: (list (list "NAME" id)) - (empty-sosofo)) - (element-title-sosofo (current-node)))) - ; Now add hr element after h1. - (make empty-element gi: "HR") - (process-children)))) - -</style-specification-body> -</style-specification> -<external-specification id="docbook" document="dbstyle"> -</style-sheet> diff --git a/db2html.xsl b/db2html.xsl new file mode 100644 index 0000000..1ef6a09 --- /dev/null +++ b/db2html.xsl @@ -0,0 +1,11 @@ +<?xml version="1.0" encoding="utf-8"?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + <xsl:import href="/usr/share/xml/docbook/stylesheet/nwalsh/html/docbook.xsl"/> + <xsl:param name="html.stylesheet">manpage.css</xsl:param> + <xsl:template name="user.header.content"> + <h1>archivemail</h1> + <hr/> + </xsl:template> +</xsl:stylesheet> + diff --git a/manpage.css b/manpage.css index e24076d..b46ad9c 100644 --- a/manpage.css +++ b/manpage.css @@ -3,9 +3,9 @@ h2 { font-variant: small-caps; font-size: 170%; } -.INFORMALEXAMPLE { +.informalexample { margin-bottom: 1.2em; } -div.INFORMALEXAMPLE .SCREEN { +div.informalexample .screen { margin-left: 2ex; } |