From 66a987a52a66aa36b3dfdb4ab8fa6af1c0d5ccf2 Mon Sep 17 00:00:00 2001
From: Daniel Kahn Gillmor <dkg@fifthhorseman.net>
Date: Tue, 10 Mar 2020 17:16:10 -0400
Subject: 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 <dkg@fifthhorseman.net>
---
 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
 
-- 
cgit v1.2.3