simplify the language in this file, and stop talking about

lists which override blacklists as whitelists;

some cleanup whilst in here;

ok millert beck

1 files changed, 49 insertions, 44 deletions

diff --git a/share/man/man5/spamd.conf.5 b/share/man/man5/spamd.conf.5
index 7bfee98deb9..05b5212cc87 100644
--- a/share/man/man5/spamd.conf.5
+++ b/share/man/man5/spamd.conf.5
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: spamd.conf.5,v 1.12 2004/01/29 17:44:29 jmc Exp $
+.\"	$OpenBSD: spamd.conf.5,v 1.13 2007/03/06 10:28:54 jmc Exp $
 .\"
 .\" Copyright (c) 2003 Jason L. Wright (jason@thought.net)
 .\" Copyright (c) 2003 Bob Beck
@@ -29,28 +29,31 @@
 .Os
 .Sh NAME
 .Nm spamd.conf
-.Nd configuration file read by
-.Xr spamd-setup 8
-for
-.Xr spamd 8
+.Nd spamd configuration file
 .Sh SYNOPSIS
-.Nm spamd.conf
+.Nm /etc/mail/spamd.conf
 .Sh DESCRIPTION
 The
 .Nm
 file is read by
 .Xr spamd-setup 8
-to configure blacklists and whitelists with corresponding
-.Xr pf 4
-table entries for
+to configure
+.Em blacklists
+for
 .Xr spamd 8 .
+Blacklists are lists of addresses of likely spammers.
+Mail from these addresses never reaches the actual mail server,
+but is instead redirected to
+.Xr spamd 8
+and tarpitted.
+.Pp
 .Nm
 follows the syntax of configuration databases as documented in
 .Xr getcap 3 .
-Example:
+Here is an example:
 .Bd -literal -offset indent
 all:\e
-	:spews1:white:myblack:
+	:spews1:override:myblack:
 
 spews1:\e
 	:black:\e
@@ -59,10 +62,10 @@ spews1:\e
 	:method=http:\e
 	:file=www.spews.org/spews_list_level1.txt:
 
-white:\e
+override:\e
 	:white:\e
 	:method=file:\e
-	:file=/var/mail/mywhite.txt:
+	:file=/var/mail/override.txt:
 
 myblack:\e
 	:black:\e
@@ -72,43 +75,46 @@ myblack:\e
 .Ed
 .Pp
 The default configuration file must include the entry
-.Ar all
-which specifies the order in which named blacklists and whitelists
+.Ar all ,
+which specifies the order in which lists
 are to be applied.
-The addresses in a whitelist are removed from the preceding blacklist.
-In the above example, if the address was present in all three lists, blacklists
+Lists are constructed by name:
+blacklists are identified by the capability
+.Pf : Ns Ar black : .
+If a list is instead given the
+.Pf : Ns Ar white :
+capability,
+addresses in it will not be blacklisted.
+The addresses in such a list are removed from the preceding blacklist.
+.Pp
+In the above example,
+if an address was present in all three lists,
+blacklists
 .Ar spews1
 and
 .Ar myblack ,
-as well as whitelist
-.Ar white ,
-the address would be removed from blacklist
+as well as the exceptions list
+.Ar override ,
+the address would be removed from list
 .Ar spews1
 by the subsequent
-.Ar white
-whitelist.
+.Ar override
+list.
 However, the address would not be removed from the
 .Ar myblack
-blacklist.
+list.
 To remove all the addresses in
-.Ar white
+.Ar override
 from
 .Ar myblack ,
-the configuration
+the following configuration
+would be used instead:
 .Bd -literal -offset indent
 all:\e
-	:spews1:white:myblack:white:
+	:spews1:override:myblack:override:
 .Ed
 .Pp
-would be used instead.
-.Pp
-Blacklists and whitelists are then constructed by name;
-blacklists are identified by the capability
-.Ar black ,
-and whitelists by the capability
-.Ar white .
-.Pp
-The source of the addresses for blacklists and whitelists is
+The source of the addresses for lists is
 specified using the
 .Ar method
 and
@@ -117,25 +123,25 @@ capability entries.
 .Pp
 .Ar method
 specifies the method by which to retrieve a file containing a list of
-addresses that consist of the blacklist or whitelist, and may be
+addresses and may be one of
 .Ar http ,
 .Ar ftp ,
-.Ar file
+.Ar file ,
 or
 .Ar exec .
-The methods
+The
 .Ar http ,
-.Ar ftp
+.Ar ftp ,
 and
 .Ar file
-capabilities will make
+methods will make
 .Nm
-retrieve a list of addresses specified in the location in the
+retrieve the file from the location specified by the
 .Ar file
-capability for the list.
+capability.
 The
 .Ar exec
-capability will make
+method will make
 .Nm
 spawn the program with arguments indicated in the
 .Ar file
@@ -185,6 +191,5 @@ and the sequence \&%A will be expanded in the message by
 to display the connecting IP address in the output.
 .Sh SEE ALSO
 .Xr ftp 1 ,
-.Xr pf 4 ,
 .Xr spamd 8 ,
 .Xr spamd-setup 8