Improved documentation.

svn path=/trunk/; revision=461

diff --git a/fetchmail.man b/fetchmail.man
index 2cb485f6afb80cef33523f3917f8397a18ac2fa7..bfd6b387aabb459bc841382c005911867383ad5a 100644 (file)
--- a/fetchmail.man
+++ b/fetchmail.man
@@ -184,7 +184,10 @@ fetched mail so that any mail IDs local to the server are expanded to
 full addresses (@ and the mailserver hostname are appended).  This enables 
 replies on the client to get addressed correctly (otherwise your
 mailer might think they should be addressed to local users on the
-client machine).  This option disables the rewrite.
+client machine!).  This option disables the rewrite.  (This option is
+provided to pacify people who are paranoid about having an MTA edit
+mail headers and want to know they can prevent it, but it is generally
+not a good idea to actually turn off rewrite.)
 .TP
 .B \-V, --version
 Displays the version information for your copy of 
@@ -572,7 +575,7 @@ to be specifying multiple users per server unless running it as root
 (thus the `pass gumshoe' would try to fetch root's mail on
 pop-provider.net, which is probably not what you want).
 In any case, we strongly recommend always having an explicit
-\&`user' clause when specifying multiple users for server.
+\&`user' clause when specifying multiple users per mailserver.
 .PP
 Here's what a simple retrieval configuration for a multi-drop mailbox
 looks like:

diff --git a/sample.rcfile b/sample.rcfile
index f1e72a4401bf1a145d01a8763410c6b6d9a98915..5ade67b25aa11f48e40b5139fffa7c15f3004909 100644 (file)
--- a/sample.rcfile
+++ b/sample.rcfile
@@ -19,18 +19,19 @@
 # arguments in this file, the command-line arguments take precedence.
 #
 # Legal keywords are
-#   server
-#   protocol (or proto) -- nuat be followed by a protocol ID
-#   port
-#   authenticate (or auth) -- must be followed by an authentication type
-#   timeout
+#   poll                      -- must be followed by a mailserver name
+#   skip                      -- must be followed by a mailserver name
+#   protocol (or proto)       -- must be followed by a protocol ID
+#   port                      -- must be followed by a TCP/IP port number
+#   authenticate (or auth)    -- must be followed by an authentication type
+#   timeout                   -- must be followed by a numeric timeout value
 #
-#   username (or user)
-#   is
-#   remotefolder (or remote)
-#   password (or pass)
-#   smtphost (or smtp)
-#   mda
+#   username (or user)        -- must be followed by a name
+#   is                        -- must be followed by one or more names
+#   remotefolder (or remote)  -- must be followed by a filename
+#   password (or pass)        -- must be followed by a password string
+#   smtphost (or smtp)        -- must be followed by a host name
+#   mda                       -- must be followed by an MDA command string
 #   keep
 #   flush
 #   fetchall
@@ -51,23 +52,25 @@
 #   login
 #   kerberos
 #
-# Basic format is
-# poll SERVERNAME protocol PROTOCOL username NAME password PASSWORD 
-# Example:
+# The noise keywords `and', `with', `has', `wants', and `options' are ignored
+# anywhere in an entry; they can be used to make it resemble English.  The
+# punctuation charactes `,' `:' `;' are also ignored. 
 #
-poll pop.provider.net protocol pop3 username jsmith password secret1
+# The run control file format is fully described (with more examples) on the
+# fetchmail manual page.
+# 
+# This is what the developer's .fetchmailrc looks like:
 
-# Or, using some abbreviations:
-#
-poll pop.provider.net proto pop3 user jsmith password secret1
+defaults password not_blowing_my_cover;
 
-# Multiple servers may be listed
-#
-poll pop.provider.net proto pop3 user jsmith password secret1
-poll other.provider.net proto pop2 user John.Smith password My^Hat
+# Use this for production
+poll locke.ccil.org with protocol APOP:
+       user esr there with password my_apop_secret is esr here;
+
+# Use this to test IMAP
+skip locke protocol IMAP:
+       user esr here is esr there;
 
-# Other possibilities
-poll pop.provider.net
-       proto pop3
-       user jsmith
-       pass secret1
+# Use this to test against POP2 using a local server
+skip localhost protocol pop2:
+       user esr here is esr there;