Package: mailscripts Version: 0.18-1 Severity: wishlist Control: tags -1 + patch X-debbugs-cc: Antoine Beaupré <[email protected]>
imap-dl's documentation was written from where i was coming from when i wrote imap-dl. Some new users have found it recently and wondered why they needed to refer to getmail documentation to understand it. This patch fixes that concern. I also want potential new features (like https://github.com/spwhitton/mailscripts/pull/1) to have a place to document any particular configuration options that they might add. You can also find the attached patch on my "documentation" branch at https://salsa.debian.org/dkg/mailscripts. Thanks for maintaining imap-dl in mailscripts! --dkg f
From 66a987a52a66aa36b3dfdb4ab8fa6af1c0d5ccf2 Mon Sep 17 00:00:00 2001 From: Daniel Kahn Gillmor <[email protected]> Date: Tue, 10 Mar 2020 17:16:10 -0400 Subject: [PATCH] imap-dl: update documentation to be less explicitly "getmail"y The fact that imap-dl came out of getmail and borrows a bit of configuration shouldn't be relevant for new users. Make the documentation more agnostic about where they're coming from. Signed-off-by: Daniel Kahn Gillmor <[email protected]> --- imap-dl | 19 ++++--------------- imap-dl.1.pod | 48 +++++++++++++++++++++++++++++++++++++----------- 2 files changed, 41 insertions(+), 26 deletions(-) diff --git a/imap-dl b/imap-dl index 469b81d..de6be60 100755 --- a/imap-dl +++ b/imap-dl @@ -17,22 +17,9 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see <https://www.gnu.org/licenses/>. -DESCRIPTION = '''A simple replacement for a minimalist use of getmail. +DESCRIPTION = '''Fetch messages from an IMAP inbox into a maildir -In particular, if you use getmail to reach an IMAP server as though it -were POP (retrieving from the server and optionally deleting), you can -point this script to the getmail config and it should do the same -thing. - -It tries to ensure that the configuration file is of the expected -type, and will terminate raising an exception, and it should not lose -messages. - -If there's any interest in supporting other similarly simple use cases -for getmail, patches are welcome. - -If you've never used getmail, you can make the simplest possible -config file like so: +Example config file: ---------- [retriever] @@ -46,6 +33,8 @@ path = /home/foo/Maildir [options] delete = True ---------- + +Run "man imap-dl" for more details. ''' import re diff --git a/imap-dl.1.pod b/imap-dl.1.pod index 9fb77c3..901c7e8 100644 --- a/imap-dl.1.pod +++ b/imap-dl.1.pod @@ -2,7 +2,7 @@ =head1 NAME -imap-dl -- a simple replacement for a minimalist user of getmail +imap-dl -- fetch messages from an IMAP inbox into a maildir =head1 SYNOPSIS @@ -10,35 +10,61 @@ B<imap-dl> [B<-v>|B<--verbose>] B<configfile>... =head1 DESCRIPTION +B<imap-dl> tries to retrieve all messages from an IMAP inbox and put +them in a maildir. + If you use getmail to reach an IMAP server as though it were POP (retrieving from the server, storing it in a maildir and optionally -deleting), you can point this script to the getmail config and it -should do the same thing. +deleting), you can point this script to the getmail configfile and it +should do the same thing. While the minimal configuration file +matches the syntax for common getmail configurations, some other +options might be specific to B<imap-dl>. -It tries to ensure that the configuration file is of the expected -type, and otherwise it will terminate with an error. It should not -lose e-mail messages. +B<imap-dl> tries to ensure that the configuration file is of the +expected type, and otherwise it will terminate with an error. It +should never lose e-mail messages. If there's any interest in supporting other similarly simple use cases -for getmail, patches are welcome. +for fetching messages from an IMAP account into a maildir, patches are +welcome. =head1 OPTIONS B<-v> or B<--verbose> causes B<imap-dl> to print more details about what it is doing. +=head1 CONFIGFILE OPTIONS + +B<imap-dl> uses an ini-style configfile, with [Sections] which each +have keyword arguments within them. We use the syntax B<foo.bar> here +to mean keyword B<bar> in section B<foo>. B<imap-dl> inherits some +basic configuration options from B<getmail>, including the following +options: + +B<retriever.server> is the dns name of the mailserver. + +B<retriever.username> is the username of the IMAP account. + +B<retriever.password> is the password for the IMAP account when using +plaintext passwords. + +B<destination.path> is the location of the target maildir. + +B<options.delete> is a boolean, whether to delete the messages that +were successfully retreived (default: false). + In addition to parts of the standard B<getmail> configuration, -B<imap-dl> supports the following keywords in the config file: +B<imap-dl> supports the following keywords in the configfile: B<options.on_size_mismatch> can be set to B<error>, B<none>, or B<warn>. This governs what to do when the remote IMAP server claims a different size in the message summary list than the actual message retrieval (default: B<error>). -=head1 EXAMPLE CONFIG +=head1 EXAMPLE CONFIGFILE -If you've never used getmail, you can make the simplest possible -config file like so: +This configfile fetches all the mail from the given IMAP account's +inbox, and deletes the messages when they are successfully fetched: =over 4 -- 2.25.1
signature.asc
Description: PGP signature
