Document expected Received: line format when parsing for envelope addressees.

svn path=/branches/BRANCH_6-3/; revision=5052

3 files changed, 22 insertions, 16 deletions

diff --git a/NEWS b/NEWS
index 206d6752..28703ed2 100644
--- a/NEWS
+++ b/NEWS
@@ -59,6 +59,9 @@ fetchmail 6.3.8 (not yet released):
   Based on a patch by Rob MacGregor.
 * Document SOCKS is not run-time configurable. Patch by Rob MacGregor.
 * Use envelope option in multidrop example. Patch by Rob MacGregor.
+* Document expected Received: line format when parsing for envelope addressees.
+* Stripped option documentation from sample.rcfile, since this is bound to go
+  out of synch with the manual page, which is the only reference on options.
 
 # CONTRIB:
 * Add delete-later and delete-later.README, a script and documentation for
@@ -74,8 +77,6 @@ fetchmail 6.3.8 (not yet released):
   64-bit mode.  Either compile 32-bit code or use GCC to compile 64-bit
   fetchmail.  Note that fetchmail doesn't take advantage of 64-bit code,
   so compiling 32-bit SPARC code should not cause any difficulties.
-* fetchmail expects Received: headers in a particular, but undocumented, format
-  when parsing envelopes.
 * fetchmail does not track pending deletes over crashes
 * the command line interface is a bit narrow-minded sometimes, for instance,
   fetchmail -s doesn't work with a running daemon
diff --git a/TODO.txt b/TODO.txt
index 8262f62a..a6150f28 100644
--- a/TODO.txt
+++ b/TODO.txt
@@ -27,7 +27,6 @@
 - add code to allow safe authentication schemes if TLS fails
 
 DOCUMENTATION:
-- document Received: parsing expectations
 - Add info whether Keywords are global, server or user keywords
 - review sample.rcfile and document it
 - consolidate multidrop documentation
diff --git a/fetchmail.man b/fetchmail.man
index f217ba91..3739724a 100644
--- a/fetchmail.man
+++ b/fetchmail.man
@@ -822,12 +822,18 @@ In the configuration file, an enhanced syntax is used:
 This option changes the header
 .I fetchmail
 assumes will carry a copy of the mail's envelope address.  Normally
-this is 'X\-Envelope\-To', but as this header is not standard, practice
-varies. See the discussion of multidrop address handling below.  As a
-special case, 'envelope "Received"' enables parsing of sendmail-style
-Received lines.  This is the default, and it should not be necessary
-unless you have globally disabled Received parsing with 'no envelope'
-in the \fI.fetchmailrc\fR file.
+this is 'X\-Envelope\-To'. Other typically found headers to carry envelope
+information are 'X\-Original\-To' and 'Delivered\-To'.  Now, since
+these headers are not standardized, practice varies. See the discussion
+of multidrop address handling below.  As a special case, 'envelope
+"Received"' enables parsing of sendmail-style Received lines.  This is
+the default, but discouraged because it is not fully reliable.
+
+.B Note
+that fetchmail expects the Received-line to be in a specific
+format: It must contain "by \fIhost\fP for \fIaddress\fR", where
+\fIhost\fP must match one of the mailserver names that fetchmail
+recognizes for the account in question.
 .sp
 The optional count argument (only available in the configuration file)
 determines how many header lines of this kind are skipped. A count of 1
@@ -2158,10 +2164,10 @@ won't be returned blindly to the author or to the list itself, but
 rather to the list manager (which is less annoying).
 
 In multidrop mode, destination headers are processed as follows:
-First, fetchmail looks for the Received: header (or whichever one is
-specified by the 'envelope' option) to determine the local
-recipient address. If the mail is addressed to more than one recipient,
-the Received line won't contain any information regarding recipient addresses.
+First, fetchmail looks for the header specified by the 'envelope' option
+in order to determine the local recipient address. If the mail is
+addressed to more than one recipient, the Received line won't contain
+any information regarding recipient addresses.
 
 Then fetchmail looks for the Resent-To:, Resent-Cc:, and Resent-Bcc:
 lines.  If they exist, they should contain the final recipients and
@@ -2604,14 +2610,14 @@ whichever of these is appropriate to wake it up.
 
 .SH BUGS AND KNOWN PROBLEMS
 .PP
+Please check the \fBNEWS\fP file that shipped with fetchmail for more
+known bugs than those listed here.
+.PP
 Fetchmail cannot handle user names that contain blanks after a "@"
 character, for instance "demonstr@ti on". These are rather uncommon and
 only hurt when using UID-based \-\-keep setups, so the 6.3.X versions of
 fetchmail won't be fixed.
 .PP
-Please check the \fBNEWS\fP file that shipped with fetchmail for more
-known bugs than those listed here.
-.PP
 The assumptions that the DNS and in particular the checkalias options
 make are not often sustainable. For instance, it has become uncommon for
 an MX server to be a POP3 or IMAP server at the same time. Therefore the