filter: fix documentation about rules

the file docs/filter-howto.txt was removed, as it contained misleading
information since it was first checked in.

it suggests the syntax for filter rules is fnmatch()-like, when in
fact they need to be specified as posix regular expressions.

additionally it contained a lot of utterly unrelated and irrelevant/
outdated text.

a few examples with the correct syntax have now been added to
tinyproxy.conf.5 manpage.

closes #212

3 files changed, 22 insertions, 55 deletions

diff --git a/docs/Makefile.am b/docs/Makefile.am
index 5065255..e2ba221 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -4,6 +4,5 @@ SUBDIRS = \
 
 EXTRA_DIST = \
 	http-error-codes.txt \
-	http-rfcs.txt \
-	filter-howto.txt
+	http-rfcs.txt
 
diff --git a/docs/filter-howto.txt b/docs/filter-howto.txt
deleted file mode 100644
index 52eab20..0000000
--- a/docs/filter-howto.txt
+++ /dev/null
@@ -1,53 +0,0 @@
-Using tinyproxy with Your Home/Small Business Network
-
-Written: Patrick L. McGillan
-Edited:  Robert James Kaes (2002-06-04)
------------------------------------------------------
-
-Being as this will be the most common usage and there were no clear
-basic instructions for this scenario, I thought I would write up what
-I did for my home system.
-
-First the layout of the network.  A cable modem is connected through a
-Linksys Router to a small hub.  The computers hanging off the hub and
-have a clear shot to the Internet.
-
-So, the connection from the Internet to the hub looks like this:
-
-   Internet->Cable TV Line->Cable Modem->Linksys Router->Hub/Switch
-
-Restricting Internet web access on some of those computers (connected
-to the hub) is what using tinyproxy is all about.  Using the web
-interface to the Linksys router, turn off all Internet access to those
-computers that shouldn't have direct access to the Internet.  This is
-done by clicking on the advanced tab and entering the IP number in the
-filter range.  Now those computers have to go through a proxy, for
-their access, as they have no direct access.
-
-On one of the Linux computers which still has Internet access (I use
-an old 486) load up tinyproxy.  Now have the users configure their
-Internet Explorer/Netscape Navigator programs to use the proxy on the
-tinyproxy computer box, along with the port number declared in the
-tinyproxy configuration file.  By default, there is no blocking of web
-sites with this program, so I created a file, called "filter", to
-start blocking some sites.
-
-Example "filter" file entries:
-
-# This is a comment
-bannerads.zwire.com
-ad.doubleclick.net
-ads.fortunecity.com
-
-This filter file usually goes into the same folder, as your
-configuration file.  Be sure and uncomment the 'Filter' line in your
-configuration file and make sure it points at your newly created
-filter file.
-
-------------------------------------------------------------------------
-
-Copyright (c) 2002  Patrick L.  McGillan <pmcgillan@dwx.com>
-
-This document is released under the same copyright license as
-tinyproxy.  You should have found a COPYING file in the top level
-directory of this distribution which contains the current license.
\ No newline at end of file
diff --git a/docs/man5/tinyproxy.conf.txt.in b/docs/man5/tinyproxy.conf.txt.in
index b5619dd..66dd04e 100644
--- a/docs/man5/tinyproxy.conf.txt.in
+++ b/docs/man5/tinyproxy.conf.txt.in
@@ -256,6 +256,27 @@ Tinyproxy supports filtering of web sites based on URLs or
 domains. This option specifies the location of the file
 containing the filter rules, one rule per line.
 
+Rules are specified as POSIX basic regular expressions (BRE), unless
+FilterExtended is activated.
+Comment lines start with a `#` character.
+
+Example filter file contents:
+
+ # filter exactly cnn.com
+ ^cnn\.com$
+ 
+ # filter all subdomains of cnn.com, but not cnn.com itself
+ .*\.cnn.com$
+ 
+ # filter any domain that has cnn.com in it, like xcnn.comfy.org
+ cnn\.com
+ 
+ # filter any domain that ends in cnn.com
+ cnn\.com$
+ 
+ # filter any domain that starts with adserver
+ ^adserver
+
 =item B<FilterURLs>
 
 If this boolean option is set to `Yes` or `On`, filtering is