Revise sample.rcfile documentation.

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

2 files changed, 13 insertions, 108 deletions

diff --git a/TODO.txt b/TODO.txt
index a6150f28..e77a6e32 100644
--- a/TODO.txt
+++ b/TODO.txt
@@ -28,5 +28,4 @@
 
 DOCUMENTATION:
 - Add info whether Keywords are global, server or user keywords
-- review sample.rcfile and document it
 - consolidate multidrop documentation
diff --git a/sample.rcfile b/sample.rcfile
index fac8e75b..1d0b09a2 100644
--- a/sample.rcfile
+++ b/sample.rcfile
@@ -18,131 +18,37 @@
 # When there is a conflict between the command-line arguments and the
 # arguments in this file, the command-line arguments take precedence.
 #
-# Legal keywords are
-#   poll                      -- must be followed by a mailserver name or label
-#   skip                      -- must be followed by a mailserver name or label
-#   via                       -- must be followed by true name of host to poll
-#   interval                  -- must be followed by an interval skip count
-#   protocol (or proto)       -- must be followed by a protocol ID
-#   uidl
-#   no uidl
-#   port                      -- must be followed by a TCP/IP port number
-#   principal                 -- must be followed by a principal name
-#   ssl
-#   sslkeyfile                -- must be followed by path to private key file
-#   sslcertfile               -- must be followed by path to certificate file
-#   authenticate (or auth)    -- must be followed by an authentication type
-#   timeout                   -- must be followed by a numeric timeout value
-#   envelope                  -- must be followed by an envelope header name
-#   qvirtual                  -- must be followed by a name prefix
-#   no envelope
-#   aka                       -- must be followed by one or more server aliases
-#   localdomains              -- must be followed by one or more domain names
-#   interface                 -- must be followed by device/IP address/mask
-#   monitor                   -- must be followed by device
-#   plugin                    -- must be followed by a string command name
-#   plugout                   -- must be followed by a string command name
-#   dns
-#   no dns
-#   checkalias                -- do multidrop address comparison by IP address
-#   no checkalias             -- do multidrop address comparison by name
-#
-#   username (or user)        -- must be followed by a name
-#   is                        -- must be followed by one or more names
-#   folder                    -- must be followed by remote folder names
-#   password (or pass)        -- must be followed by a password string
-#   smtphost (or smtp)        -- must be followed by host names
-#   smtpaddress               -- must be followed by a host name
-#   antispam                  -- must be followed by a numeric response value
-#   mda                       -- must be followed by an MDA command string
-#   bsmtp                     -- must be followed by a filename or -
-#   lmtp
-#   preconnect (or pre)       -- must be followed by an executable command
-#   postconnect (or post)     -- must be followed by an executable command
-#
-#   keep
-#   flush
-#   fetchall
-#   rewrite
-#   forcecr
-#   stripcr
-#   pass8bits
-#   dropstatus
-#   mimedecode
-#   idle
-#   no keep
-#   no flush
-#   no fetchall
-#   no rewrite
-#   no forcecr
-#   no stripcr
-#   no pass8bits
-#   no dropstatus
-#   no mimedecode
-#   no idle
-#   limit                     -- must be followed by numeric size limit
-#   warnings                  -- must be followed by numeric size limit
-#   fetchlimit                -- must be followed by numeric msg fetch limit
-#   batchlimit                -- must be followed by numeric SMTP batch limit
-#   expunge                   -- must be followed by numeric delete count
-#   properties                -- must be followed by a string
-#
-# Legal protocol identifiers are
-#   pop2 (or POP2)
-#   pop3 (or POP3)
-#   imap (or IMAP)
-#   imap-k4 (or IMAP-K4)
-#   apop (or APOP)
-#   rpop (or RPOP)
-#   kpop (or KPOP)
-#   etrn (or ETRN)
-#
-# Add ssl for protocols operating over an SSL connection (POP3 and IMAP)
-#   Default port for IMAPS (IMAP over SSL) is 993
-#   Default port for POP3S (POP3 over SSL) is 995
-#      Taken from assigned numbers and compatible with netscape/outlook usage.
-#
-# Legal authentication types are
-#   login
-#   kerberos
-#   kerberos_v5
-#
-# Legal global option statements are
-#
-#   set logfile			-- must be followed by a string
-#   set idfile			-- must be followed by a string
-#   set postmaster		-- must be followed by a string
-#   set daemon			-- must be followed by a number   
-#   set syslog
-#   set invisible
-#   set showdots
-#
-# 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 characters `,' `:' `;' are also ignored. 
-#
 # 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:
+#
+# This is what the former developer's .fetchmailrc looks like:
 
-set daemon 300	# Poll at 5-minute intervals
+set daemon 300	# Sleep 300 seconds after the poll, then poll again.
 
 defaults
+	# only poll when the sl0 interface is up (only available on some systems)
 	interface "sl0/10.0.2.15"	# SLIRP standard address
+	# log in with name "esr" and do multidrop fetch for the users
+	# esr, fetchmail-friends, and magic-numbers
 	user esr is esr fetchmail-friends magic-numbers here
+	# fetch (and delete after retrieval) all messages
 	fetchall
 
 # Use this for production
 poll imap.example.org protocol IMAP:
+	# do not use MX lookups to check of server aliases, but pass
+	# them explicitly:
 	no dns, aka snark.thyrsus.com thyrsus.com locke.example.org example.org 
 	password my_remote_password;
 
 # Use this to test POP3
 skip pop3.example.org with protocol APOP:
+	# do not use MX lookups to check of server aliases, but pass
+	# them explicitly:
 	no dns, aka snark.thyrsus.com thyrsus.com locke.example.org example.org 
 	password my_apop_secret;
 
-# Use this to test against a different server
+# Use this to test against a different server - it is skipped unless
+# you give its name on fetchmail's command line.
 skip pop3.netaxs.com:
 	password my_netaxs.password;