Manpage, TODO, CHANGELOG: document and record wildcard expansion in IMAP mailbox names

3 files changed, 21 insertions, 3 deletions

diff --git a/CHANGELOG b/CHANGELOG
index 216259e..1ad6daf 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -68,6 +68,9 @@ Version 0.8.0   - UNRELEASED
     Like the --suffix and --prefix options, it is expanded with strftime().
     This option conflicts with archiving multiple mailboxes.  Closes: feature
     request #1306538.
+  * archivemail now expands wildcards in IMAP mailbox names.  For example, the
+    url imaps://user@server/foo/* will expand to all subfolders of foo.
+    Closes: feature request #1978540. Obsoletes: patch #1918937.
 
 Version 0.7.2   - 9 November 2007
 
diff --git a/TODO b/TODO
index e650636..e6950ed 100644
--- a/TODO
+++ b/TODO
@@ -50,8 +50,6 @@ date-string").  This should be done without any real network I/O.
 Try to port archivemail to email.message and the new mailboxes in Python 2.5.
 Is these flexible enough for our needs?
 
-Add recursive archiving of mail subfolders? 
-
 Line out what we want with respect to multiple selection criteria. 
 Some make sense, but this easily gets too complex, and if only it's a hassle
 with adding all the options.  Hm.  
diff --git a/archivemail.sgml b/archivemail.sgml
index 543cfc5..94f03a8 100644
--- a/archivemail.sgml
+++ b/archivemail.sgml
@@ -35,7 +35,7 @@
 
 <RefEntry>
 
-<DocInfo><Date>31 July 2010</Date></DocInfo>
+<DocInfo><Date>9 August 2010</Date></DocInfo>
 
 <RefMeta>
 <RefEntryTitle>archivemail</RefEntryTitle>
@@ -97,6 +97,11 @@ mailboxes, but always writes <application/mbox/-format archives.
 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. 
@@ -626,6 +631,18 @@ that are older than 90 days to compressed mailboxes in the
     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>