From f6be896b1f8467f48a0f1edccb43c0a2a9eb4e6a Mon Sep 17 00:00:00 2001 From: Nikolaus Schulz Date: Wed, 29 Dec 2010 01:03:09 +0100 Subject: Port man page from SGML to XML --- MANIFEST.in | 2 +- Makefile | 14 +- archivemail.1 | 1284 +++++++++++++++++++++++++++++++++++------------------- archivemail.sgml | 715 ------------------------------ archivemail.xml | 718 ++++++++++++++++++++++++++++++ db2html.dsl | 40 -- db2html.xsl | 11 + manpage.css | 4 +- 8 files changed, 1582 insertions(+), 1206 deletions(-) delete mode 100644 archivemail.sgml create mode 100644 archivemail.xml delete mode 100644 db2html.dsl create mode 100644 db2html.xsl 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 diff --git a/Makefile b/Makefile index cbf8651..4432631 100644 --- a/Makefile +++ b/Makefile @@ -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: -.\" -.\" Please send any bug reports, improvements, comments, patches, -.\" etc. to Steve Cheng . -.TH "ARCHIVEMAIL" "1" "09 August 2010" "SP" "" - -.SH NAME +'\" t +.\" Title: archivemail +.\" Author: [see the "Author" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" 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 +.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 \&. Updated and supplemented by Nikolaus Schulz - +.sp +This manual page was written by Paul Rodger \&. 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 @@ - - -"> - - - -"> - - - -"> - - - -"> - - - -"> - - - -"> - - - -"> - - - -"> -]> - - - -9 August 2010 - - -archivemail -1 -SP - - - -archivemail -archive and compress your old email - - - - - - - - - - - - -Description - - -archivemail is a tool for archiving and compressing old email in mailboxes. -By default it will read the mailbox - - -By default, 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. - - - - - - - Messages that are flagged important are not archived or deleted unless - explicitly requested with the option. - Also, - - -To archive an imap://username:password@server/mailbox - to specify the mailbox. -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 --pwfile option to make --pwfile option is set, - - - -Options - - - - - - -Archive messages older than - - - - - -Archive messages older than - - - - - -Use the directory name - - - - -Read - - - - - -Append - - - - - -Prefix --suffix option for a list of valid - - - - - - - -Use the suffix _archive, unless a prefix is specified. - - - -Like a prefix, the suffix - - Locale's abbreviated weekday name. - - Locale's full weekday name. - - Locale's abbreviated month name. - - Locale's full month name. - - Locale's appropriate date and time representation. - - Day of the month as a decimal number [01,31]. - - Hour (24-hour clock) as a decimal number [00,23]. - - Hour (12-hour clock) as a decimal number [01,12]. - - Day of the year as a decimal number [001,366]. - - Month as a decimal number [01,12]. - - Minute as a decimal number [00,59]. - - Locale's equivalent of either AM or PM. - - Second as a decimal number [00,61]. (1) - - 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. - - Weekday as a decimal number [0(Sunday),6]. - - 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. - - Locale's appropriate date representation. - - Locale's appropriate time representation. - - Year without century as a decimal number [00,99]. - - Year with century as a decimal number. - - Time zone name (or by no characters if no time zone exists). - - A literal "%" character. - - - - - - - - -Use - - - - - -Only archive messages that are - - - - - - - -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. - - - - - - - - -Do not archive any messages that have not yet been read. :2, then it assumes the message has been read. - - - - - - - - -Do not mangle lines in message bodies beginning with "From ". When archiving -a message from a mailbox not in ' to them, since mail -user agents might otherwise interpret these lines as message separators. -Messages from - - - - - - - -Delete rather than archive old mail. Use this option with caution! - - - - - - - - -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 - - - - - - - -Archive all messages, without distinction. - - - - - - - - -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. - - - - - - - - -Do not compress any archives. - - - - - - - - -Warn about duplicate - - - - - - - -Reports lots of extra debugging information about what is going on. - - - - - - - -Set - - - - - - - -Turns on quiet mode. Do not print any statistics about how many messages were -archived. This should be used if you are running - - - - - - - -Display the version of - - - - - - - -Display brief summary information about how to run - - - - - - -Notes - -.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 &lockf;. -The archive is locked in the same way when it is updated. - - - - - - - - - - When archiving mailboxes with leading dots in the name, - --prefix or - 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. - - - - A conversion from other formats to &mbox; will silently overwrite existing - - - -<acronym/IMAP/ - -When - - -<acronym/IMAP/ <acronym/URLs/ - -RFC 2882 (Internet Message -Format) rules for the local-part of email addresses -in mind. -So, rather than enforcing an imap://"username@bogus.com":"password"@imap.bogus.com/mailbox -. -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. - - - - - - - - - -Examples - - - -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: - -bash$ archivemail debian-user - - - - - - -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: - -bash$ archivemail --suffix '_%B_%Y' debian-user - - - - - - -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: - -bash$ archivemail --date'1 Jan 2002' cm-melb - - - - - - -Exactly the same as the above example, using an ISO date format instead: - -bash$ archivemail --date=2002-01-01 cm-melb - - - - - - -To delete all messages in the mailbox spam that -are older than 30 days: - -bash$ archivemail --delete --days=30 spam - - - - - - -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: - -bash$ archivemail --preserve-unread incoming - - - - - - -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: - -bash$ archivemail --no-compress received - - - - - - -To archive all mailboxes in the directory $HOME/Mail -that are older than 90 days to compressed mailboxes in the -$HOME/Mail/Archive directory: - -bash$ archivemail -d90 -o $HOME/Mail/Archive $HOME/Mail/* - - - - - - - To archive all mails older than 180 days from the given $HOME/Mail/Archive directory, quoting the password and - reading it from the environment variable PASSWORD: - - - -bash$ archivemail -o $HOME/Mail/Archive imaps://user:'"'$PASSWORD'"'@example.org/INBOX - - - Note the protected quotes. - - - - - - To archive all mails older than 180 days in subfolders of "foo" on the - given ~/imap-pass.txt: - - - bash$ archivemail --pwfile=~/imap-pass.txt imaps://user@example.org/foo/* - - - - - -Tips - -Probably the best way to run --quiet option. -Don't forget to try the and perhaps the - option for non-destructive testing. - - - - -Exit Status -Normally the exit status is 0. Nonzero indicates an unexpected error. - - - - -Bugs - -If an imap://user@example.com/folder/subfolder and -imap://user@example.com/folder.subfolder will be -archived in subfolder_archive.gz and -folder.subfolder_archive.gz, respectively, although they -might refer to the same - - - - - - - - -See Also - - &python;, &gzip;, &mutt;, &procmail; - - - - -Url -The sourceforge - - - - -Author - This manual page was written by Paul Rodger <paul at paulrodger dot -com>. Updated and supplemented by Nikolaus Schulz -microschulz@web.de - - - diff --git a/archivemail.xml b/archivemail.xml new file mode 100644 index 0000000..6542351 --- /dev/null +++ b/archivemail.xml @@ -0,0 +1,718 @@ + + +lockf +2"> + + +gzip +1"> + + +mutt +1"> + + +procmail +1"> + + +python +1"> + + +seteuid +2"> + + +crontab +5"> + + +mbox +5"> +]> + + + +9 August 2010 + + +archivemail +1 +SP + + + +archivemail +archive and compress your old email + + + + + +archivemail + +MAILBOX + + + + + +Description + + +archivemail is a tool for archiving and compressing old email in mailboxes. +By default it will read the mailbox 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. + + + +By default, archivemail derives the archive filename from the +mailbox name by appending an _archive suffix to the mailbox +name. For example, if you run archivemail 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. + + + +archivemail supports reading IMAP, +Maildir, MH and mbox-format +mailboxes, but always writes mbox-format archives. + + + + Messages that are flagged important are not archived or deleted unless + explicitly requested with the option. + Also, archivemail can be configured not to archive unread mail, or + to only archive messages larger than a specified size. + + + +To archive an IMAP-format mailbox, use the format +imap://username:password@server/mailbox + to specify the mailbox. +archivemail will expand wildcards in IMAP 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 + option to make archivemail read the +password from a file, or alternatively just enter it upon request. +If the option is set, archivemail does not +look for a password in the URL, and the colon is not considered a +delimiter. +Substitute 'imap' with 'imaps', and +archivemail will establish a secure SSL connection. +See below for more IMAP peculiarities. + + + + +Options + + + + + + + +Archive messages older than NUM days. +The default is 180. This option is incompatible with the + option below. + + + + + + + +Archive messages older than DATE. +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 above. + + + + + + + +Use the directory name PATH to store the +mailbox archives. The default is the same directory as the mailbox to be +read. + + + + + + + +Read IMAP password from file 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. + + + + + + + +Append STRING to the IMAP filter string. +For IMAP wizards. + + + + + + + +Prefix NAME to the archive name. +NAME is expanded by the &python; function +time.strftime(), which means that you can specify special +directives in NAME to make an archive named after the archive +cut-off date. +See the discussion of the option for a list of valid +strftime() directives. +The default is not to add a prefix. + + + + + + + + +Use the suffix NAME to create the filename used for archives. +The default is _archive, unless a prefix is specified. + + + +Like a prefix, the suffix NAME is expanded by the &python; +function time.strftime() with the archive cut-off date. +time.strftime() understands the following directives: + + + + Locale's abbreviated weekday name. + + Locale's full weekday name. + + Locale's abbreviated month name. + + Locale's full month name. + + Locale's appropriate date and time representation. + + Day of the month as a decimal number [01,31]. + + Hour (24-hour clock) as a decimal number [00,23]. + + Hour (12-hour clock) as a decimal number [01,12]. + + Day of the year as a decimal number [001,366]. + + Month as a decimal number [01,12]. + + Minute as a decimal number [00,59]. + + Locale's equivalent of either AM or PM. + + Second as a decimal number [00,61]. (1) + + 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. + + Weekday as a decimal number [0(Sunday),6]. + + 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. + + Locale's appropriate date representation. + + Locale's appropriate time representation. + + Year without century as a decimal number [00,99]. + + Year with century as a decimal number. + + Time zone name (or by no characters if no time zone exists). + + A literal "%" character. + + + + + + + + + +Use NAME as the archive name, ignoring the name +of the mailbox that is archived. +Like prefixes and suffixes, NAME 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. + + + + + + + +Only archive messages that are NUM bytes or +greater. + + + + + + + + +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. + + + + + + + + +Do not archive any messages that have not yet been read. archivemail +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 'RO' or 'OR' then archivemail assumes the +message has been read. archivemail determines if a +maildir message has +been read by looking at the filename. If the filename contains an 'S' after +:2, then it assumes the message has been read. + + + + + + + + +Do not mangle lines in message bodies beginning with "From ". When archiving +a message from a mailbox not in mbox format, by default +archivemail mangles such lines by prepending a '>' to them, since mail +user agents might otherwise interpret these lines as message separators. +Messages from mbox folders are never mangled. See &mbox; for more +information. + + + + + + + + +Delete rather than archive old mail. Use this option with caution! + + + + + + + + +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, and mainly useful for +testing purposes. +Note that multiple passes will create duplicates, since messages are blindly +appended to an existing archive. + + + + + + + + +Archive all messages, without distinction. + + + + + + + + +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. + + + + + + + + +Do not compress any archives. + + + + + + + + +Warn about duplicate Message-IDs that appear in the input +mailbox. + + + + + + + +Reports lots of extra debugging information about what is going on. + + + + + + + + +Set IMAP debugging level. This makes archivemail dump its +conversation with the IMAP server and some internal IMAP +processing to stdout. Higher values for NUM give more +elaborate output. Set NUM to 4 to see all exchanged +IMAP commands. (Actually, NUM is just passed +literally to imaplib.Debug.) + + + + + + + + +Turns on quiet mode. Do not print any statistics about how many messages were +archived. This should be used if you are running archivemail from +cron. + + + + + + + + +Display the version of archivemail and exit. + + + + + + + + +Display brief summary information about how to run archivemail. + + + + + + + +Notes + +archivemail requires &python; version 2.3 or later. +When reading an mbox-format mailbox, archivemail 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 &lockf;. +The archive is locked in the same way when it is updated. +archivemail will also complain and abort if a 3rd-party modifies the +mailbox while it is being read. + + + +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 0600. +If archivemail finds a pre-existing archive mailbox it +will append rather than overwrite that archive. +archivemail will refuse to operate on mailboxes that are symbolic +links. + + + +archivemail 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. + + + + When archiving mailboxes with leading dots in the name, + archivemail will strip the dots off the archive name, so + that the resulting archive file is not hidden. + This is not done if the or + 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. + + + + A conversion from other formats to &mbox; will silently overwrite existing + Status and X-Status message headers. + + + +<acronym>IMAP</acronym> + +When archivemail processes an IMAP 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 IMAP works. +This does not apply, however, if you run archivemail with the options + or . + + +archivemail 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. + +<acronym>IMAP</acronym> <acronym>URLS</acronym> + +archivemail's 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 '@' or ':', just +quote it like this: +imap://"username@bogus.com":"password"@imap.bogus.com/mailbox +. +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. + + +archivemail 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. + + + + + + + +Examples + + + +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: + +bash$ archivemail debian-user + + + + + + +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: + +bash$ archivemail --suffix '_%B_%Y' debian-user + + + + + + +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: + +bash$ archivemail --date'1 Jan 2002' cm-melb + + + + + + +Exactly the same as the above example, using an ISO date format instead: + +bash$ archivemail --date=2002-01-01 cm-melb + + + + + + +To delete all messages in the mailbox spam that +are older than 30 days: + +bash$ archivemail --delete --days=30 spam + + + + + + +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: + +bash$ archivemail --preserve-unread incoming + + + + + + +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: + +bash$ archivemail --no-compress received + + + + + + +To archive all mailboxes in the directory $HOME/Mail +that are older than 90 days to compressed mailboxes in the +$HOME/Mail/Archive directory: + +bash$ archivemail -d90 -o $HOME/Mail/Archive $HOME/Mail/* + + + + + + + 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 PASSWORD: + + + +bash$ archivemail -o $HOME/Mail/Archive imaps://user:'"'$PASSWORD'"'@example.org/INBOX + + + Note the protected quotes. + + + + + + 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: + + +bash$ archivemail --pwfile=~/imap-pass.txt imaps://user@example.org/foo/* + + + + + +Tips + +Probably the best way to run archivemail is from your &crontab; +file, using the option. +Don't forget to try the and perhaps the + option for non-destructive testing. + + + + +Exit Status +Normally the exit status is 0. Nonzero indicates an unexpected error. + + + + +Bugs + +If an 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 +IMAP URL, however, the whole path will be considered +the basename of the mailbox. +E.g. the two URLs +imap://user@example.com/folder/subfolder and +imap://user@example.com/folder.subfolder will be +archived in subfolder_archive.gz and +folder.subfolder_archive.gz, respectively, although they +might refer to the same IMAP mailbox. + + +archivemail 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. + + + +archivemail is still too slow, but if you are running from &crontab; +you won't 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. + + + + +See Also + + &python;, &gzip;, &mutt;, &procmail; + + + + +Url +The archivemail home page is currently hosted at +sourceforge + + + + +Author + This manual page was written by Paul Rodger <paul at paulrodger dot +com>. Updated and supplemented by Nikolaus Schulz +microschulz@web.de + + + diff --git a/db2html.dsl b/db2html.dsl deleted file mode 100644 index cac5775..0000000 --- a/db2html.dsl +++ /dev/null @@ -1,40 +0,0 @@ - -]> - - - - - -(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)))) - - - - - diff --git a/db2html.xsl b/db2html.xsl new file mode 100644 index 0000000..1ef6a09 --- /dev/null +++ b/db2html.xsl @@ -0,0 +1,11 @@ + + + + manpage.css + +

archivemail

+
+ + + 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; } -- cgit v1.2.3