Added hint for startup on Red Hat

[privoxy.git] / doc / source / user-manual.sgml

diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml
index d599631..672c9a2 100644 (file)
--- a/doc/source/user-manual.sgml
+++ b/doc/source/user-manual.sgml
@@ -15,6 +15,7 @@
 <!entity % p-text "IGNORE">        <!-- define we are not a text only doc -->
 <!entity % p-doc "INCLUDE">        <!-- and we are a formal doc           -->
 <!entity % p-readme "IGNORE">
 <!entity % p-text "IGNORE">        <!-- define we are not a text only doc -->
 <!entity % p-doc "INCLUDE">        <!-- and we are a formal doc           -->
 <!entity % p-readme "IGNORE">

+<!entity % p-config "IGNORE">

 <!entity % p-supp-userman "IGNORE"> <!-- Omit some from supported.sgml    -->
 ]>
 <!--
 <!entity % p-supp-userman "IGNORE"> <!-- Omit some from supported.sgml    -->
 ]>
 <!--


@@ -24,7 +25,7 @@
                 This file belongs into
                 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
                 
                 This file belongs into
                 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
                 

- $Id: user-manual.sgml,v 1.78 2002/04/17 18:04:16 oes Exp $
+ $Id: user-manual.sgml,v 1.88 2002/04/23 05:37:54 hal9 Exp $

 
  Written by and Copyright (C) 2001 the SourceForge
  Privoxy team. http://www.privoxy.org/
 
  Written by and Copyright (C) 2001 the SourceForge
  Privoxy team. http://www.privoxy.org/


@@ -45,7 +46,7 @@
 <artheader>
 <title>Privoxy User Manual</title>
 
 <artheader>
 <title>Privoxy User Manual</title>
 

-<pubdate>$Id: user-manual.sgml,v 1.78 2002/04/17 18:04:16 oes Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 1.88 2002/04/23 05:37:54 hal9 Exp $</pubdate>

 
 <authorgroup>
  <author>
 
 <authorgroup>
  <author>


@@ -100,7 +101,6 @@
 <!--   ~~~~~       New section      ~~~~~     -->
 
 <sect1 label="1" id="introduction"><title>Introduction</title>
 <!--   ~~~~~       New section      ~~~~~     -->
 
 <sect1 label="1" id="introduction"><title>Introduction</title>

-

 <para>
  This documentation is included with the current &p-status; version of
  <application>Privoxy</application>, v.&p-version;<![%p-not-stable;[, 
 <para>
  This documentation is included with the current &p-status; version of
  <application>Privoxy</application>, v.&p-version;<![%p-not-stable;[, 


@@ -112,8 +112,8 @@
  stable v3.0 is <quote>soon</quote> ;-)]]>.
 </para>
 
  stable v3.0 is <quote>soon</quote> ;-)]]>.
 </para>
 

-<![%p-not-stable;[

 <!-- include only in non-stable versions -->
 <!-- include only in non-stable versions -->

+<![%p-not-stable;[

 <para>
  Since this is a &p-status; version, not all new features are well tested. This
  documentation may be slightly out of sync as a result (especially with 
 <para>
  Since this is a &p-status; version, not all new features are well tested. This
  documentation may be slightly out of sync as a result (especially with 


@@ -130,7 +130,6 @@
  features of ad and banner blocking and cookie management,
  <application>Privoxy</application> provides new features<![%p-not-stable;[,
  some of them currently under development]]>:
  features of ad and banner blocking and cookie management,
  <application>Privoxy</application> provides new features<![%p-not-stable;[,
  some of them currently under development]]>:

-<anchor id="testing"/>

 </para>
 
 <!-- Include newfeatures.sgml boilerplate here: -->
 </para>
 
 <!-- Include newfeatures.sgml boilerplate here: -->


@@ -145,12 +144,14 @@
 
 <!--   ~~~~~       New section      ~~~~~     -->
 <sect1 id="installation"><title>Installation</title>
 
 <!--   ~~~~~       New section      ~~~~~     -->
 <sect1 id="installation"><title>Installation</title>

+

 <para>
  <application>Privoxy</application> is available both in convenient pre-compiled
  packages for a wide range of operating systems, and as raw source code.
  For most users, we recommend using the packages, which can be downloaded from our
  <ulink url="http://sourceforge.net/projects/ijbswa/">Privoxy Project Page</ulink>.
 </para>
 <para>
  <application>Privoxy</application> is available both in convenient pre-compiled
  packages for a wide range of operating systems, and as raw source code.
  For most users, we recommend using the packages, which can be downloaded from our
  <ulink url="http://sourceforge.net/projects/ijbswa/">Privoxy Project Page</ulink>.
 </para>

+

 <para>
  If you like to live on the bleeding edge and are not afraid of using
  possibly unstable development versions, you can check out the up-to-the-minute
 <para>
  If you like to live on the bleeding edge and are not afraid of using
  possibly unstable development versions, you can check out the up-to-the-minute


@@ -166,36 +167,56 @@
 
 <!--   ~~~~~       New section      ~~~~~     -->
 <sect2 id="installation-packages"><title>Binary Packages</title>
 
 <!--   ~~~~~       New section      ~~~~~     -->
 <sect2 id="installation-packages"><title>Binary Packages</title>

+
+<para>
+ Note: If you have a previous <application>Junkbuster</application> or
+ <application>Privoxy</application> installation on your system, you
+ will need to remove it.  Some platforms do this for you as part 
+ of their installation procedure. (See below for your platform).
+</para>
+

 <para>
 <para>

- Binary packages can be downloaded from our <ulink
- url="http://sourceforge.net/projects/ijbswa/">Privoxy Project Page</ulink>.
+ In any case <emphasis>be sure to backup your old configuration
+ if it is valuable to you.</emphasis> See the
+ <link linkend="upgradersnote">note to upgraders</link>.

 </para>
 
 <para>
 </para>
 
 <para>

- How to install them depends on your operating system:
+ How to install the binary packages depends on your operating system:

 </para>
 
 <!--   ~~~~~       New section      ~~~~~     -->
 </para>
 
 <!--   ~~~~~       New section      ~~~~~     -->

-<sect3 id="installation-pack-rpm"><title>Redhat and SuSE RPMs</title>
+<sect3 id="installation-pack-rpm"><title>Red Hat and SuSE RPMs</title>
+
+<para>
+ RPMs can be installed with <literal>rpm -Uvh privoxy-&p-version;-1.rpm</literal>,
+ and will use <filename>/etc/privoxy</filename> for the location 
+ of configuration files.
+</para>

 
 <para>
 
 <para>

- RPMs can be installed with <literal>rpm -Uvh &lt;name-of-rpm.rpm&gt;</literal>,
- and will use <filename>/etc/privoxy</filename> for configuration files.
+ Note that on Red Hat, Privoxy will not be automatically started on system
+ boot. You will need to enable that using linuxconf.

 </para>
 
 <para>
 </para>
 
 <para>

- Note that if you have a <application>Junkbuster</application> RPM installed
+ If you have problems with failed dependencies, try rebuilding the SRC RPM: 
+ <literal>rpm --rebuild privoxy-&p-version;-1.src.rpm;</literal>. This 
+ will use your locally installed libraries and RPM version. 
+</para>
+
+<para>
+ Also note that if you have a <application>Junkbuster</application> RPM installed

  on your system, you need to remove it first, because the packages conflict.
  on your system, you need to remove it first, because the packages conflict.

+ Otherwise, RPM will try to remove <application>Junkbuster</application>
+ automatically, before installing <application>Privoxy</application>.

 </para>
 </sect3>
 
 <!--   ~~~~~       New section      ~~~~~     -->
 </para>
 </sect3>
 
 <!--   ~~~~~       New section      ~~~~~     -->

-<sect3 id="installation-pack-bintgz"><title>Solaris, NetBSD, HP-UX</title>
-
+<sect3 id="installation-deb"><title>Debian</title>

 <para>
 <para>

- Create a new directory, <literal>cd</literal> to it, then unzip and
- untar the archive. For the most part, you'll have to figure out where
- things go. FIXME.
+ FIXME.

 </para>
 </sect3>
 
 </para>
 </sect3>
 


@@ -208,12 +229,29 @@
 </para>
 </sect3>
 
 </para>
 </sect3>
 

+<!--   ~~~~~       New section      ~~~~~     -->
+<sect3 id="installation-pack-bintgz"><title>Solaris, NetBSD, FreeBSD, HP-UX</title>
+
+<para>
+ Create a new directory, <literal>cd</literal> to it, then unzip and
+ untar the archive. For the most part, you'll have to figure out where
+ things go. FIXME.
+</para>
+</sect3>
+

 <!--   ~~~~~       New section      ~~~~~     -->
 <sect3 id="installation-os2"><title>OS/2</title>
 
 <para>
 <!--   ~~~~~       New section      ~~~~~     -->
 <sect3 id="installation-os2"><title>OS/2</title>
 
 <para>

- Just double-click the WarpIN self-installing archive, which will guide
- you through the installation process. A shadow of the
+ First, make sure that no previous installations of
+ <application>Junkbuster</application> and / or 
+ <application>Privoxy</application> are left on your
+ system. You can do this by 
+</para>
+
+<para>
+ Then, just double-click the WarpIN self-installing archive, which will
+ guide you through the installation process. A shadow of the

  <application>Privoxy</application> executable will be placed in your
  startup folder so it will start automatically whenever OS/2 starts.
 </para>
  <application>Privoxy</application> executable will be placed in your
  startup folder so it will start automatically whenever OS/2 starts.
 </para>


@@ -225,16 +263,36 @@
 </sect3>
 
 <!--   ~~~~~       New section      ~~~~~     -->
 </sect3>
 
 <!--   ~~~~~       New section      ~~~~~     -->

-<sect3 id="installation-deb"><title>Debian</title>
-<para>
- FIXME.
+<sect3 id="installation-mac"><title>Max OSX</title>
+<para>
+ Unzip the downloaded package (you can either double-click on the file
+ in the finder, or on the desktop if you downloaded it there).  Then,
+ double-click on the package installer icon and follow the installation
+ process.
+ <application>Privoxy</application> will be installed in the subdirectory
+ <literal>/Applications/Privoxy.app</literal>.
+ <application>Privoxy</application> will set itself up to start 
+ automatically on system bringup via
+ <literal>/System/Library/StartupItems/Privoxy</literal>.

 </para>
 </sect3>
 
 <!--   ~~~~~       New section      ~~~~~     -->
 <sect3 id="installation-amiga"><title>AmigaOS</title>
 <para>
 </para>
 </sect3>
 
 <!--   ~~~~~       New section      ~~~~~     -->
 <sect3 id="installation-amiga"><title>AmigaOS</title>
 <para>

- Unpack the <literal>.lha</literal> archive, then FIXME.
+ Copy and then unpack the <filename>lha</filename> archive to a suitable location. 
+ All necessary files will be installed into <application>Privoxy</application>
+ directory, including all configuration and log files. To uninstall, just 
+ remove this directory.
+</para>
+<para>
+ Start <application>Privoxy</application> (with RUN &lt;&gt;NIL:) in your
+ <filename>startnet</filename> script (AmiTCP), in
+ <filename>s:user-startup</filename> (RoadShow), as startup program in your
+ startup script (Genesis), or as startup action (Miami and MiamiDx). 
+ <application>Privoxy</application> will automatically quit when you quit your
+ TCP/IP stack (just ignore the harmless warning your TCP/IP stack may display that
+ <application>Privoxy</application> is still running).

 </para>
 </sect3>
 </sect2>
 </para>
 </sect3>
 </sect2>


@@ -245,13 +303,6 @@
 <!-- include buildsource.sgml boilerplate: -->
 &buildsource;
 <!-- end boilerplate -->
 <!-- include buildsource.sgml boilerplate: -->
 &buildsource;
 <!-- end boilerplate -->

-
-<para>
- For more detailed instructions, on how to build Redhat and SuSE RPMs,
- Windows self-extracting installers etc, and for building from CVS sources,
- please consult the <ulink url="../developer-manual/newrelease.html">developer
- manual</ulink>.
-</para>

 </sect2>
 
 </sect1>
 </sect2>
 
 </sect1>


@@ -280,8 +331,8 @@
 </para>
 <para>
  A <quote>filter file</quote> (typically <filename>default.filter</filename>)
 </para>
 <para>
  A <quote>filter file</quote> (typically <filename>default.filter</filename>)

- is new with <application>Privoxy 2.9.x</application>, and provides some
- of the new  sophistication (explained below). <filename>config</filename> is 
+ is new as of <application>Privoxy 2.9.x</application>, and provides some
+ of the new sophistication (explained below). <filename>config</filename> is 

  much the same as before.
 </para>
 <para>
  much the same as before.
 </para>
 <para>


@@ -289,9 +340,8 @@
  files, and possibly adapt any personal rules from your older files.
  When porting personal rules over from the old <filename>blockfile</filename>
  to the new actions file, please note that even the pattern syntax has
  files, and possibly adapt any personal rules from your older files.
  When porting personal rules over from the old <filename>blockfile</filename>
  to the new actions file, please note that even the pattern syntax has

- changed.
- If upgrading from 2.9.x development versions, it is still recommended 
- to use the new configuration files.
+ changed. If upgrading from 2.9.x development versions, it is still
+ recommended to use the new configuration files.

 </para>
 <para>
  A quick list of things to be aware of before upgrading: 
 </para>
 <para>
  A quick list of things to be aware of before upgrading: 


@@ -352,8 +402,8 @@
  Before launching <application>Privoxy</application> for the first time, you 
  will want to configure your browser(s) to use <application>Privoxy</application>
  as a HTTP and HTTPS proxy. The default is localhost for the proxy address,
  Before launching <application>Privoxy</application> for the first time, you 
  will want to configure your browser(s) to use <application>Privoxy</application>
  as a HTTP and HTTPS proxy. The default is localhost for the proxy address,

- and port 8118 (earlier versions used port 8000). This is the one required 
- configuration that must be done! 
+ and port 8118 (earlier versions used port 8000). This is the one
+ configuration step that must be done! 

 </para>
  
 <para> 
 </para>
  
 <para> 


@@ -370,7 +420,7 @@
  After doing this, flush your browser's disk and memory caches to force a
  re-reading of all pages and to get rid of any ads that may be cached. You 
  are now ready to start enjoying the benefits of using
  After doing this, flush your browser's disk and memory caches to force a
  re-reading of all pages and to get rid of any ads that may be cached. You 
  are now ready to start enjoying the benefits of using

- <application>Privoxy</application>.
+ <application>Privoxy</application>!

 </para>
 
 
 </para>
 
 


@@ -389,7 +439,11 @@
 </para>
 
 <para>
 </para>
 
 <para>

- An init script is provided for SuSE and Redhat.
+ See <link linkend="cmdoptions">below</link> for other command line options.
+</para>
+
+<para>
+ An init script is provided for SuSE and Red Hat.

 </para>
 
 <para>
 </para>
 
 <para>


@@ -397,7 +451,7 @@
 </para>
 
 <para>
 </para>
 
 <para>

- For RedHat: <command>/etc/rc.d/init.d/privoxy start</command>
+ For Red Hat and Debian: <command>/etc/rc.d/init.d/privoxy start</command>

 </para>
 
 
 </para>
 
 


@@ -500,7 +554,7 @@
 
 
 <!--   ~~~~~       New section      ~~~~~     -->
 
 
 <!--   ~~~~~       New section      ~~~~~     -->

-<sect2>
+<sect2 id="cmdoptions">

 <title>Command Line Options</title>
 <para>
  <application>Privoxy</application> may be invoked with the following
 <title>Command Line Options</title>
 <para>
  <application>Privoxy</application> may be invoked with the following


@@ -515,7 +569,7 @@
     <emphasis>--version</emphasis>
   </para>
   <para>
     <emphasis>--version</emphasis>
   </para>
   <para>

-     Print version info and exit, Unix only.
+     Print version info and exit. Unix only.

   </para>
  </listitem> 
  <listitem>
   </para>
  </listitem> 
  <listitem>


@@ -523,7 +577,7 @@
     <emphasis>--help</emphasis>
   </para>
   <para>
     <emphasis>--help</emphasis>
   </para>
   <para>

-   Print a short usage info and exit, Unix only.
+   Print short usage info and exit. Unix only.

   </para>
  </listitem> 
  <listitem>
   </para>
  </listitem> 
  <listitem>


@@ -532,7 +586,7 @@
   </para>
   <para>
    Don't become a daemon, i.e. don't fork and become process group
   </para>
   <para>
    Don't become a daemon, i.e. don't fork and become process group

-   leader, don't detach from controlling tty. Unix only.
+   leader, and don't detach from controlling tty. Unix only.

   </para>
  </listitem> 
  <listitem>
   </para>
  </listitem> 
  <listitem>


@@ -567,7 +621,8 @@
     <application>Privoxy</application> will look for a file named 
     <quote>config</quote> in the current directory (except on Win32 
     where it will look for <quote>config.txt</quote> instead). Specify 
     <application>Privoxy</application> will look for a file named 
     <quote>config</quote> in the current directory (except on Win32 
     where it will look for <quote>config.txt</quote> instead). Specify 

-    full path to avoid confusion.
+    full path to avoid confusion. If no config file is found, 
+    <application>Privoxy</application> will fail to start.

   </para>
  </listitem> 
 
   </para>
  </listitem> 
 


@@ -636,9 +691,9 @@ Please choose from the following options:
  it as a test to see whether it is <application>Privoxy</application> 
  causing the problem or not. <application>Privoxy</application> continues 
  to run as a proxy in this case, but all filtering is disabled. There
  it as a test to see whether it is <application>Privoxy</application> 
  causing the problem or not. <application>Privoxy</application> continues 
  to run as a proxy in this case, but all filtering is disabled. There

- is even a toggle Bookmarklet offered, so that you can toggle
- <application>Privoxy</application> with one click from your browser.
-
+ is even a toggle <link linkend="bookmarklets">Bookmarklet</link> offered, so
+ that you can toggle <application>Privoxy</application> with one click from
+ your browser.

 </para>
 
 </sect2>
 </para>
 
 </sect2>


@@ -682,7 +737,7 @@ Please choose from the following options:
    <para>
     <filename>default.action</filename> (the actions file) is used to define
     which of a set of various <quote>actions</quote> relating to images, banners, 
    <para>
     <filename>default.action</filename> (the actions file) is used to define
     which of a set of various <quote>actions</quote> relating to images, banners, 

-    pop-ups, access restrictions, banners and cookies are to be applied where.
+    pop-ups, access restrictions, banners and cookies are to be applied, and where.

     There is a web based editor for this file that can be accessed at <ulink
     url="http://config.privoxy.org/edit-actions/">http://config.privoxy.org/edit-actions/</ulink>
     (Shortcut: <ulink url="http://p.p/edit-actions/">http://p.p/edit-actions/</ulink>).
     There is a web based editor for this file that can be accessed at <ulink
     url="http://config.privoxy.org/edit-actions/">http://config.privoxy.org/edit-actions/</ulink>
     (Shortcut: <ulink url="http://p.p/edit-actions/">http://p.p/edit-actions/</ulink>).


@@ -715,7 +770,8 @@ Please choose from the following options:
 
 <para>
  <filename>default.action</filename> and <filename>default.filter</filename> 
 
 <para>
  <filename>default.action</filename> and <filename>default.filter</filename> 

- can use Perl style regular expressions for maximum flexibility.
+ can use Perl style <link linkend="regex">regular expressions</link> for
+ maximum flexibility. 

 </para>
 
 <para>
 </para>
 
 <para>


@@ -775,7 +831,7 @@ Please choose from the following options:
 
 <para>
  The main config file controls all aspects of <application>Privoxy</application>'s
 
 <para>
  The main config file controls all aspects of <application>Privoxy</application>'s

- operation that are not location dependent (i.e. they apply to all URLs, no matter
+ operation that are not location dependent (i.e. they apply universally, no matter

  where you may be surfing).
 </para>
 
  where you may be surfing).
 </para>
 


@@ -1022,7 +1078,7 @@ Please choose from the following options:
    <para>
     Your logfile will grow indefinitely, and you will probably want to
     periodically remove it.  On Unix systems, you can do this with a cron job
    <para>
     Your logfile will grow indefinitely, and you will probably want to
     periodically remove it.  On Unix systems, you can do this with a cron job

-    (see <quote>man cron</quote>). For Redhat, a <command>logrotate</command> 
+    (see <quote>man cron</quote>). For Red Hat, a <command>logrotate</command> 

     script has been included.
    </para> 
    <para>
     script has been included.
    </para> 
    <para>


@@ -2088,7 +2144,7 @@ Please choose from the following options:
 <para>
  Now, your users can set their browser's proxy to use either
  host-a or host-b and be able to browse the internal content
 <para>
  Now, your users can set their browser's proxy to use either
  host-a or host-b and be able to browse the internal content

- on both isp-a or isp-b.
+ of both isp-a and isp-b.

 </para>
 
 <para>
 </para>
 
 <para>


@@ -2134,9 +2190,6 @@ Please choose from the following options:
 
 <sect3>
 <title>Windows GUI Options</title>
 
 <sect3>
 <title>Windows GUI Options</title>

-<!--
-Removed references to Win32. HB 09/23/01
--->

 <para>
  <application>Privoxy</application> has a number of options specific to the
  Windows GUI interface:
 <para>
  <application>Privoxy</application> has a number of options specific to the
  Windows GUI interface:


@@ -2330,13 +2383,20 @@ Removed references to Win32. HB 09/23/01
  See below for a complete list of available actions.
 </para>
 
  See below for a complete list of available actions.
 </para>
 

+<para>
+ An actions file typically has sections. At the top, <quote>aliases</quote> are 
+ defined (discussed below), then the default set of rules which will apply 
+ universally to all sites and pages. And then below that is generally a lengthy 
+ set of exceptions to the defined universal policies.
+</para>
+

 <!--   ~~~~~       New section      ~~~~~     -->
 <sect3>
 <title>Finding the Right Mix</title>
 <para>
  Note that some actions like cookie suppression or script disabling may
  render some sites unusable, which rely on these techniques to work properly.
 <!--   ~~~~~       New section      ~~~~~     -->
 <sect3>
 <title>Finding the Right Mix</title>
 <para>
  Note that some actions like cookie suppression or script disabling may
  render some sites unusable, which rely on these techniques to work properly.

- Finding the right mix of actions is not easy and a matter of personal
+ Finding the right mix of actions is not easy and certainly a matter of personal

  taste. In general, it can be said that the more <quote>aggressive</quote>
  your default settings (in the top section of the actions file) are,
  the more exceptions for <quote>trusted</quote> sites you will have to
  taste. In general, it can be said that the more <quote>aggressive</quote>
  your default settings (in the top section of the actions file) are,
  the more exceptions for <quote>trusted</quote> sites you will have to


@@ -2404,26 +2464,27 @@ Removed references to Win32. HB 09/23/01
 <sect3>
 <title>Patterns</title>
 <para>
 <sect3>
 <title>Patterns</title>
 <para>

- Generally, a pattern has the form &lt;domain&gt;/&lt;path&gt;, where both the
- &lt;domain&gt; and &lt;path&gt; part are optional. If you only specify a
- domain part, the <quote>/</quote> can be left out:
+ Generally, a pattern has the form <literal>&lt;domain&gt;/&lt;path&gt;</literal>,
+ where both the <literal>&lt;domain&gt;</literal> and <literal>&lt;path&gt;</literal>
+ are optional. (This is why the pattern <literal>/</literal> matches all URLs).

 </para>
 
 <variablelist>
  <varlistentry>
 </para>
 
 <variablelist>
  <varlistentry>

-  <term><literal>www.example.com</literal></term>
+  <term><literal>www.example.com/</literal></term>

   <listitem>
    <para>
   <listitem>
    <para>

-    is a domain only pattern and will match any request to <literal>www.example.com</literal>,
+    is a domain-only pattern and will match any request to <literal>www.example.com</literal>,

     regardless of which document on that server is requested.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
     regardless of which document on that server is requested.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>

-  <term><literal>www.example.com/</literal></term>
+  <term><literal>www.example.com</literal></term>

   <listitem>
    <para>
   <listitem>
    <para>

-    means exactly the same.
+    means exactly the same. For domain-only patterns, the trailing <literal>/</literal> may
+    be omitted.

    </para>
   </listitem>
  </varlistentry>
    </para>
   </listitem>
  </varlistentry>


@@ -2562,7 +2623,7 @@ Removed references to Win32. HB 09/23/01
 </para>
 
 <para>
 </para>
 
 <para>

- Note that the pattern is automatically left-anchored at the <quote>/</quote>,
+ Note that the path pattern is automatically left-anchored at the <quote>/</quote>,

  i.e. it matches as if it would start with a <quote>^</quote>.
 </para>
 
  i.e. it matches as if it would start with a <quote>^</quote>.
 </para>
 


@@ -2582,16 +2643,16 @@ Removed references to Win32. HB 09/23/01
 <!--  ~  End section  ~  -->
 
 
 <!--  ~  End section  ~  -->
 
 

-

 <!--   ~~~~~       New section      ~~~~~     -->
 
 <!--   ~~~~~       New section      ~~~~~     -->
 

-<sect3>
+<sect3 id="actions">

 <title>Actions</title>
 <para>
  Actions are enabled if preceded with a <quote>+</quote>, and disabled if 
  preceded with a <quote>-</quote>. Actions are invoked by enclosing the 
  action name in curly braces (e.g. {+some_action}), followed by a list of 
 <title>Actions</title>
 <para>
  Actions are enabled if preceded with a <quote>+</quote>, and disabled if 
  preceded with a <quote>-</quote>. Actions are invoked by enclosing the 
  action name in curly braces (e.g. {+some_action}), followed by a list of 

- URLs to which the action applies. There are three classes of actions:
+ URLs (or patterns that match URLs) to which the action applies. There are
+ three classes of actions: 

 </para>
 
 <para>
 </para>
 
 <para>


@@ -2599,8 +2660,9 @@ Removed references to Win32. HB 09/23/01
 
  <listitem>
   <para>  
 
  <listitem>
   <para>  

-   Boolean (e.g. <quote>+/-block</quote>):
-  </para>
+   Boolean, i.e the action can only be <quote>on</quote> or
+   <quote>off</quote>. Examples: 
+ </para>

   <para>
    <literal>
     <msgtext> 
   <para>
    <literal>
     <msgtext> 


@@ -2616,14 +2678,16 @@ Removed references to Win32. HB 09/23/01
 
  <listitem>
   <para>  
 
  <listitem>
   <para>  

-   parameterized (e.g. <quote>+/-hide-user-agent</quote>):
+   Parameterized, e.g. <quote>+/-hide-user-agent{ Mozilla 1.0 }</quote>, 
+   where some value is required in order to enable this type of action.
+   Examples:

   </para>
   <para>
    <literal>
     <msgtext> 
      <literallayout>
   <emphasis>{+name{param}}</emphasis>  # enable action and set parameter to <quote>param</quote>
   </para>
   <para>
    <literal>
     <msgtext> 
      <literallayout>
   <emphasis>{+name{param}}</emphasis>  # enable action and set parameter to <quote>param</quote>

-  <emphasis>{-name}</emphasis>         # disable action
+  <emphasis>{-name}</emphasis>         # disable action (<quote>parameter</quote>) can be omitted

      </literallayout>
     </msgtext> 
    </literal>
      </literallayout>
     </msgtext> 
    </literal>


@@ -2632,15 +2696,18 @@ Removed references to Win32. HB 09/23/01
  
  <listitem>
   <para>  
  
  <listitem>
   <para>  

-   Multi-value (e.g. <quote>{+/-add-header{Name: value}}</quote>, <quote>{+/-wafer{name=value}}</quote>):
+  <!-- oes, or someone, check this. Re-worded 04/20/02 HB. -->
+   Multi-value, e.g. <quote>{+/-add-header{Name: value}}</quote> ot
+   <quote>{+/-wafer{name=value}}</quote>), where some value needs to be defined
+   in addition to simply enabling the actino. Examples:

   </para>
   <para>
    <literal>
     <msgtext> 
      <literallayout>
   </para>
   <para>
    <literal>
     <msgtext> 
      <literallayout>

-  <emphasis>{+name{param}}</emphasis>   # enable action and add parameter <quote>param</quote>
-  <emphasis>{-name{param}}</emphasis>   # remove the parameter <quote>param</quote>
-  <emphasis>{-name}</emphasis>          # disable this action totally
+  <emphasis>{+name{param=value}}</emphasis>   # enable action and set <quote>param</quote> to <quote>value</quote>
+  <emphasis>{-name{param=value}}</emphasis>   # remove the parameter <quote>param</quote> completely
+  <emphasis>{-name}</emphasis>                # disable this action totally and remove <application>param</application> too

      </literallayout>
     </msgtext> 
    </literal>
      </literallayout>
     </msgtext> 
    </literal>


@@ -2666,549 +2733,1296 @@ Removed references to Win32. HB 09/23/01
  specified.
 </para>
 
  specified.
 </para>
 

+<!-- start actions listing -->

 <para>
  The list of valid <application>Privoxy</application> <quote>actions</quote> are:
 </para>
 
 <para>
  The list of valid <application>Privoxy</application> <quote>actions</quote> are:
 </para>
 

-<para>
- <itemizedlist>
- 
- <listitem>
-  <para>  
-   Add the specified HTTP header, which is not checked for validity.
-   You may specify this many times to specify many different headers:
-  </para>
-  <para>
-   <literal>
-    <msgtext> 
-     <literallayout>
-  <emphasis>+add-header{Name: value}</emphasis>
-     </literallayout>
-    </msgtext> 
-   </literal>
-  </para>
- </listitem>
- 
- 
- <listitem>
-  <para>  
-   Block this URL totally. In a default installation, a <quote>blocked</quote>
-   URL will result in bright red banner that says <quote>BLOCKED</quote>, 
-   with a reason why it is being blocked, and an option to see it anyway.
-   The page displayed for this is the <quote>blocked</quote> template 
-   file.
-  </para>
-  <para>
-   <literal>
-    <msgtext> 
-     <literallayout>
-  <emphasis>+block</emphasis>
-     </literallayout>
-    </msgtext> 
-   </literal>
-  </para>
- </listitem>
- 
- 
- <listitem>
-  <para>  
-   De-animate all animated GIF images, i.e. reduce them to their last frame.
-   This will also shrink the images considerably (in bytes, not pixels!). If
-   the option <quote>first</quote> is given, the first frame of the animation
-   is used as the replacement. If <quote>last</quote> is given, the last frame
-   of the animation is used instead, which probably makes more sense for most
-   banner animations, but also has the risk of not showing the entire last
-   frame (if it is only a delta to an earlier frame).
-  </para>
-  <para>
-   <literal>
-    <msgtext> 
-     <literallayout>
-  <emphasis>+deanimate-gifs{last}</emphasis>
-  <emphasis>+deanimate-gifs{first}</emphasis>
-     </literallayout>
-    </msgtext> 
-   </literal>
-  </para>
- </listitem>
+
+<!-- ********************************************************** -->
+<!-- Please note the below defined actions use id's that are    -->
+<!-- probably linked from other places, so please don't change. -->
+<!--                                                            -->
+<!-- ********************************************************** -->
+
+
+<!--   ~~~~~       New section      ~~~~~     -->
+
+<sect4 id="add-header">
+<title><emphasis>+add-header{Name: value}</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+  <term>Type:</term>
+  <!-- boolean, parameterized, Multi-value -->
+  <listitem>
+   <para>Multi-value.</para>
+  </listitem>
+ </varlistentry>

  
  

- <listitem>
-  <para>
-   <quote>+downgrade</quote> will downgrade HTTP/1.1 client requests to
-   HTTP/1.0 and downgrade the responses as well. Use this action for servers
-   that use HTTP/1.1 protocol features that
-   <application>Privoxy</application> doesn't handle well yet. HTTP/1.1 
-   is only partially implemented. Default is not to downgrade requests.
-  </para>
-  <para>
-   <literal>
-    <msgtext> 
-     <literallayout>
-  <emphasis>+downgrade</emphasis>
-     </literallayout>
-    </msgtext> 
-   </literal>
-  </para>
- </listitem> 
+ <varlistentry>
+  <term>Typical uses:</term>
+  <listitem>
+   <para>
+    Send a user defined HTTP header to the web server.
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Possible values:</term>
+  <listitem>
+   <para>
+    Any value is possible. Validity of the defined HTTP headers is not checked.
+   </para>
+  </listitem>
+ </varlistentry>

  
  

- <listitem>
-  <para>  
-   Many sites, like yahoo.com, don't just link to other sites. Instead, they
-   will link to some script on their own server, giving the destination as a
-   parameter, which will then redirect you to the final target. URLs resulting
-   from this scheme typically look like:
-   <emphasis>http://some.place/some_script?http://some.where-else</emphasis>.
-  </para>
-  <para>
-   Sometimes, there are even multiple consecutive redirects encoded in the
-   URL. These redirections via scripts make your web browsing more traceable,
-   since the server from which you follow such a link can see where you go to.
-   Apart from that, valuable bandwidth and time is wasted, while your browser
-   ask the server for one redirect after the other. Plus, it feeds the
-   advertisers.
-  </para>
-  <para>
-   The <quote>+fast-redirects</quote> option enables interception of these
-   types of requests by <application>Privoxy</application>, who will cut off
-   all but the last valid URL in the request and send a local redirect back to
-   your browser without contacting the intermediate site(s).
-  </para>
-  <para>
-   <literal>
-    <msgtext> 
-     <literallayout>
-  <emphasis>+fast-redirects</emphasis>
-     </literallayout>
-    </msgtext> 
-   </literal>
-  </para>
- </listitem>
+ <varlistentry>
+  <term>Example usage:</term>
+  <listitem>
+    <literallayout>
+     <emphasis>{+add-header{X-User-Tracking: sucks}}</emphasis>
+     <emphasis>.example.com</emphasis>
+    </literallayout>
+  </listitem>
+ </varlistentry>

 
 

- <listitem>
-  <para>  
-   Apply the filters in the <literal>section_header</literal> 
-   section of the <filename>default.filter</filename> file to the site(s).
-   <filename>default.filter</filename> sections are grouped according to like
-   functionality. <application>Filters</application> can be used to 
-   re-write any of the raw page content. This is a potentially a 
-   very powerful feature!
-  </para> 
-   
-  <para>
-   <literal>
-    <msgtext> 
-     <literallayout>
- <emphasis>+filter{section_header}</emphasis>
-     </literallayout>
-    </msgtext> 
-   </literal>
-  </para>
+<varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    This action may be specified multiple times, in order to define multiple 
+    headers. This is rarely needed for the typical user. If you don't know what 
+    <quote>HTTP headers</quote> are, you definitely don't need to worry about this 
+    one.
+   </para>
+  </listitem>
+ </varlistentry>
+</variablelist>
+</sect4>

 
 

-  <para>   
-   Filter sections that are pre-defined in the supplied
-   <filename>default.filter</filename> include:
-  </para>

 
 

- <blockquote>
-  <simplelist>
-   <member>
-     <emphasis>html-annoyances</emphasis>:  Get rid of particularly annoying HTML abuse.
-   </member>
-  </simplelist>
-  <simplelist>
-   <member>
-    <emphasis>js-annoyances</emphasis>:    Get rid of particularly annoying JavaScript abuse
-   </member>
-  </simplelist>
-  <simplelist>
-   <member>
-    <emphasis>no-popups</emphasis>:         Kill all popups in JS and HTML
-   </member>
-  </simplelist>
-  <simplelist>
-   <member>
-    <emphasis>frameset-borders</emphasis>: Give frames a border
-   </member>
-  </simplelist>
-  <simplelist>
-   <member>
-    <emphasis>webbugs</emphasis>:          Squish WebBugs (1x1 invisible GIFs used for user tracking)
-   </member>
-  </simplelist>
-  <simplelist>
-   <member>
-    <emphasis>no-refresh</emphasis>:       Automatic refresh sucks on auto-dialup lines
-   </member>
-  </simplelist>
-  <simplelist>
-   <member>
-    <emphasis>fun</emphasis>:              Text replacements  for subversive browsing fun!
-   </member>
-  </simplelist>
-  <simplelist>
-   <member>
-    <emphasis>nimda</emphasis>:            Remove (virus) Nimda code.
-   </member>
-  </simplelist>
-  <simplelist>
-   <member>
-     <emphasis>banners-by-size</emphasis>:  Kill banners by size
-   </member>
-  </simplelist>
-  <simplelist>
-   <member>
-    <emphasis>crude-parental</emphasis>:   Kill all web pages that contain the words "sex" or "warez"
-   </member>
-  </simplelist>
- </blockquote>
+<!--   ~~~~~       New section      ~~~~~     -->
+<sect4 id="block">
+<title><emphasis>+block</emphasis></title>

 
 

- <para>
-  Note: Filtering requires buffering the page content, which may appear to slow down
-  page rendering since nothing is displayed until all content has passed 
-  the filters. (It does not really take longer, but seems that way since 
-  the page is not incrementally displayed.) This effect will be more noticeable
-  on slower connections.
-</para>
+<variablelist>
+ <varlistentry>
+  <term>Type:</term>
+  <!-- boolean, parameterized, Multi-value -->
+  <listitem>
+   <para>Boolean.</para>
+  </listitem>
+ </varlistentry>

 
 

- </listitem>
+ <varlistentry>
+  <term>Typical uses:</term>
+  <listitem>
+   <para>
+    Used to block a URL from reaching your browser. The URL may be 
+    anything, but is typically used to block ads or other obnoxious 
+    content.    
+   </para>
+  </listitem>
+ </varlistentry>

 
 

- <listitem>
-  <para>  
-   Block any existing X-Forwarded-for header, and do not add a new one:
-  </para>
-  <para>
-   <literal>
-    <msgtext> 
-     <literallayout>
-  <emphasis>+hide-forwarded</emphasis>
-     </literallayout>
-    </msgtext> 
-   </literal>
-  </para>
- </listitem>
+ <varlistentry>
+  <term>Possible values:</term>
+  <listitem>
+   <para>N/A</para>
+  </listitem>
+ </varlistentry>
+ 
+ <varlistentry>
+  <term>Example usage:</term>
+  <listitem>
+    <literallayout>
+     <emphasis>{+block}</emphasis>
+     <emphasis>.example.com</emphasis>
+     <emphasis>.ads.r.us</emphasis>
+    </literallayout>
+  </listitem>
+ </varlistentry>

 
 

- <listitem>
-  <para>  
-   If the browser sends a <quote>From:</quote> header containing your e-mail
-   address, this either completely removes the header (<quote>block</quote>), or
-   changes it to the specified e-mail address.
-  </para>
-  <para>
-   <literal>
-    <msgtext> 
-     <literallayout>
-  <emphasis>+hide-from{block}</emphasis>
-  <emphasis>+hide-from{spam@sittingduck.xqq}</emphasis>
-     </literallayout>
-    </msgtext> 
-   </literal>
+<varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    <application>Privoxy</application> will display its 
+    special <quote>BLOCKED</quote> page if a URL matches one of the 
+    blocked patterns. If there is sufficient space, a large red 
+    banner will appear with a friendly message about why the page 
+    was blocked, and a way to go there anyway. If there is insufficient 
+    space a smaller blocked page will appear without the red banner.
+    One exception is if the URL matches both <quote>+block</quote> 
+    and <quote>+image</quote>, then it can be handled by 
+    <quote>+image-blocker</quote> (see below).
+   </para>
+  </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+
+<!--   ~~~~~       New section      ~~~~~     -->
+<sect4 id="deanimate-gifs">
+<title><emphasis>+deanimate-gifs</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+  <term>Type:</term>
+  <!-- boolean, parameterized, Multi-value -->
+  <listitem>
+   <para>Parameterized.</para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Typical uses:</term>
+  <listitem>
+   <para>
+    To stop those annoying, distracting animated GIF images.
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Possible values:</term>
+  <listitem>
+   <para>
+    <quote>last</quote> or <quote>first</quote>
+   </para>
+  </listitem>
+ </varlistentry>
+ 
+ <varlistentry>
+  <term>Example usage:</term>
+  <listitem>
+    <literallayout>
+      <emphasis>{+deanimate-gifs{last}}</emphasis>
+      <emphasis>.example.com</emphasis>
+    </literallayout>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    De-animate all animated GIF images, i.e. reduce them to their last frame.
+    This will also shrink the images considerably (in bytes, not pixels!). If
+    the option <quote>first</quote> is given, the first frame of the animation
+    is used as the replacement. If <quote>last</quote> is given, the last
+    frame of the animation is used instead, which probably makes more sense for
+    most banner animations, but also has the risk of not showing the entire
+    last frame (if it is only a delta to an earlier frame).
+   </para>
+  </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+<!--   ~~~~~       New section      ~~~~~     -->
+<sect4 id="downgrade">
+<title><emphasis>+downgrade</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+  <term>Type:</term>
+  <!-- boolean, parameterized, Multi-value -->
+  <listitem>
+   <para>Boolean.</para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Typical uses:</term>
+  <listitem>
+   <para>
+    <quote>+downgrade</quote> will downgrade HTTP/1.1 client requests to
+    HTTP/1.0 and downgrade the responses as well.
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Possible values:</term>
+  <listitem>
+   <para>
+    N/A
+   </para>
+  </listitem>
+ </varlistentry>
+ 
+ <varlistentry>
+  <term>Example usage:</term>
+  <listitem>
+    <literallayout>
+     <emphasis>{+downgrade}</emphasis>
+     <emphasis>.example.com</emphasis>
+    </literallayout>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    Use this action for servers that use HTTP/1.1 protocol features that
+    <application>Privoxy</application> doesn't handle well yet. HTTP/1.1 is
+    only partially implemented. Default is not to downgrade requests. This is
+    an infrequently needed action, and is used to help with problem sites only.
+   </para>
+  </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+<!--   ~~~~~       New section      ~~~~~     -->
+<sect4 id="fast-redirects">
+<title><emphasis>+fast-redirects</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+  <term>Type:</term>
+  <!-- boolean, parameterized, Multi-value -->
+  <listitem>
+   <para>Boolean.</para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Typical uses:</term>
+  <listitem>
+   <para>
+    The <quote>+fast-redirects</quote> action enables interception of 
+    <quote>redirect</quote> requests from one server to another, which 
+    are used to track users.<application>Privoxy</application> can cut off
+    all but the last valid URL in redirect request and send a local redirect
+    back to your browser without contacting the intermediate site(s).
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Possible values:</term>
+  <listitem>
+   <para>
+    N/A
+   </para>
+  </listitem>
+ </varlistentry>
+ 
+ <varlistentry>
+  <term>Example usage:</term>
+  <listitem>
+    <literallayout>
+     <emphasis>{+fast-redirects}</emphasis>
+     <emphasis>.example.com</emphasis>
+    </literallayout>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>  
+    Many sites, like yahoo.com, don't just link to other sites. Instead, they
+    will link to some script on their own server, giving the destination as a
+    parameter, which will then redirect you to the final target. URLs
+    resulting from this scheme typically look like:
+    <emphasis>http://some.place/some_script?http://some.where-else</emphasis>.

   </para>
   </para>

- </listitem>
+   <para>
+    Sometimes, there are even multiple consecutive redirects encoded in the
+    URL. These redirections via scripts make your web browsing more traceable,
+    since the server from which you follow such a link can see where you go
+    to. Apart from that, valuable bandwidth and time is wasted, while your
+    browser ask the server for one redirect after the other. Plus, it feeds
+    the advertisers.
+   </para>
+   <para>
+    This is a normally on feature, and often requires exceptions for sites that
+    are sensitive to defeating this mechanism.
+   </para>
+  </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+
+<!--   ~~~~~       New section      ~~~~~     -->
+<sect4 id="filter">
+<title><emphasis>+filter</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+  <term>Type:</term>
+  <!-- boolean, parameterized, Multi-value -->
+  <listitem>
+   <para>Parameterized.</para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Typical uses:</term>
+  <listitem>
+   <para>
+    Apply page filtering as defined by named sections of the
+    <filename>default.filter</filename> file to the specified site(s). 
+    <quote>Filtering</quote> can be any modification of the raw 
+    page content, including re-writing or deletion.
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Possible values:</term>
+  <listitem>
+   <para>
+    <quote>+filter</quote> must include the name of one of the section identifiers
+    from <filename>default.filter</filename> (or whatever
+    <emphasis>filterfile</emphasis> is specified in <filename>config</filename>).
+   </para>
+  </listitem>
+ </varlistentry>

  
  

- <listitem>
+ <varlistentry>
+  <term>Example usage (from the current <filename>default.filter</filename>):</term>
+  <listitem>
+   <simplelist>
+   <member>
+    <emphasis>+filter{html-annoyances}</emphasis>:  Get rid of particularly annoying HTML abuse.
+   </member>
+  </simplelist>
+  <simplelist>
+   <member>
+    <emphasis>+filter{js-annoyances}</emphasis>:    Get rid of particularly annoying JavaScript abuse
+   </member>
+  </simplelist>
+  <simplelist>
+   <member>
+    <emphasis>+filter{content-cookies}</emphasis>:   Kill cookies that come in the HTML or JS content 
+   </member>
+  </simplelist>
+  <simplelist>
+   <member>
+    <emphasis>+filter{popups}</emphasis>:         Kill all popups in JS and HTML
+   </member>
+  </simplelist>
+  <simplelist>
+   <member>
+    <emphasis>+filter{frameset-borders}</emphasis>: Give frames a border and make them resizable 
+   </member>
+  </simplelist>
+  <simplelist>
+   <member>
+    <emphasis>+filter{webbugs}</emphasis>:          Squish WebBugs (1x1 invisible GIFs used for user tracking)
+   </member>
+  </simplelist>
+  <simplelist>
+   <member>
+    <emphasis>+filter{refresh-tags}</emphasis>:     Kill automatic refresh tags (for dial-on-demand setups) 
+   </member>
+  </simplelist>
+  <simplelist>
+   <member>
+    <emphasis>+filter{fun}</emphasis>:              Text replacements  for subversive browsing fun!
+   </member>
+  </simplelist>
+  <simplelist>
+   <member>
+    <emphasis>+filter{nimda}</emphasis>:            Remove Nimda (virus) code.
+   </member>
+  </simplelist>
+  <simplelist>
+   <member>
+    <emphasis>+filter{banners-by-size}</emphasis>:  Kill banners by size (<emphasis>very</emphasis> efficient!)
+   </member>
+  </simplelist>
+  <simplelist>
+   <member>
+    <emphasis>+filter{shockwave-flash}</emphasis>:   Kill embedded Shockwave Flash objects
+   </member>
+  </simplelist>
+  <simplelist>
+   <member>
+    <emphasis>+filter{crude-parental}</emphasis>:   Kill all web pages that contain the words "sex" or "warez"
+   </member>
+  </simplelist>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    This is potentially a very powerful feature! And requires a knowledge 
+    of regular expressions if you want to <quote>roll your own</quote>.
+   </para>
+   <para>
+    Filtering requires buffering the page content, which may appear to
+    slow down page rendering since nothing is displayed until all content has
+    passed the filters. (It does not really take longer, but seems that way
+    since the page is not incrementally displayed.) This effect will be more
+    noticeable on slower connections.
+   </para>
+  </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+
+<!--   ~~~~~       New section      ~~~~~     -->
+<sect4 id="hide-forwarded">
+<title><emphasis>+hide-forwarded</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+  <term>Type:</term>
+  <!-- Boolean, Parameterized, Multi-value -->
+  <listitem>
+   <para>Boolean.</para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Typical uses:</term>
+  <listitem>
+   <para>
+    Block any existing X-Forwarded-for HTTP header, and do not add a new one.
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Possible values:</term>
+  <listitem>
+   <para>
+    N/A
+   </para>
+  </listitem>
+ </varlistentry>
+ 
+ <varlistentry>
+  <term>Example usage:</term>
+  <listitem>
+    <literallayout>
+     <emphasis>{+hide-forwarded}</emphasis>
+     <emphasis>.example.com</emphasis>
+    </literallayout>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    It is fairly safe to leave this on. It does not seem to break many sites.
+   </para>
+  </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+
+<!--   ~~~~~       New section      ~~~~~     -->
+<sect4 id="hide-from">
+<title><emphasis>+hide-from</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+  <term>Type:</term>
+  <!-- Boolean, Parameterized, Multi-value -->
+  <listitem>
+   <para>Parameterized.</para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Typical uses:</term>
+  <listitem>
+   <para>
+    To block the browser from sending your email address in a <quote>From:</quote>
+    header.
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Possible values:</term>
+  <listitem>
+   <para>
+    Keyword: <quote>block</quote>, or any user defined value.
+   </para>
+  </listitem>
+ </varlistentry>
+ 
+ <varlistentry>
+  <term>Example usage:</term>
+  <listitem>
+    <literallayout>
+     <emphasis>{+hide-from{block}}</emphasis>
+     <emphasis>.example.com</emphasis>
+    </literallayout>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    The keyword <quote>block</quote> will completely remove the header.
+    Alternately, you can specify any value you prefer to send to the web
+    server.
+   </para>
+  </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+
+<!--   ~~~~~       New section      ~~~~~     -->
+<sect4 id="hide-referer">
+<title><emphasis>+hide-referer</emphasis></title>
+<anchor id="hide-referrer">
+
+<variablelist>
+ <varlistentry>
+  <term>Type:</term>
+  <!-- Boolean, Parameterized, Multi-value -->
+  <listitem>
+   <para>Parameterized.</para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Typical uses:</term>
+  <listitem>
+   <para>
+     Don't send the <quote>Referer:</quote> (sic) HTTP header to the web site.
+     Or, alternately send a forged header instead.
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Possible values:</term>
+  <listitem>
+   <para>
+     Prevent the header from being sent with the keyword, <quote>block</quote>.
+     Or, <quote>forge</quote> a URL to one from the same server as the request.
+     Or, set to user defined value of your choice.
+   </para>
+  </listitem>
+ </varlistentry>
+ 
+ <varlistentry>
+  <term>Example usage:</term>
+  <listitem>
+    <literallayout>
+     <emphasis>{+hide-referer{forge}}</emphasis>
+     <emphasis>.example.com</emphasis>
+    </literallayout>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    <quote>forge</quote> is the preferred option here, since some servers will
+    not send images back otherwise.
+   </para>

   <para>  
   <para>  

-   Don't send the <quote>Referer:</quote> (sic) header to the web site.  You
-   can block it, forge a URL to the same server as the request (which is
-   preferred because some sites will not send images otherwise) or set it to a
-   constant, user defined string of your choice.
-  </para>
-  <para>
-   <literal>
-    <msgtext> 
-     <literallayout>
-  <emphasis>+hide-referer{block}</emphasis>
-  <emphasis>+hide-referer{forge}</emphasis>
-  <emphasis>+hide-referer{http://nowhere.com}</emphasis>
-     </literallayout>
-    </msgtext> 
-   </literal>
+   <quote>+hide-referrer</quote> is an alternate spelling of
+   <quote>+hide-referer</quote>. It has the exact same parameters, and can be freely
+   mixed with, <quote>+hide-referer</quote>. (<quote>referrer</quote> is the
+   correct English spelling, however the HTTP specification has a bug - it
+   requires it to be spelled as <quote>referer</quote>.) 

   </para>
   </para>

- </listitem>
+  </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+
+<!--   ~~~~~       New section      ~~~~~     -->
+<sect4 id="hide-user-agent">
+<title><emphasis>+hide-user-agent</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+  <term>Type:</term>
+  <!-- Boolean, Parameterized, Multi-value -->
+  <listitem>
+   <para>Parameterized.</para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Typical uses:</term>
+  <listitem>
+   <para>
+    To change the <quote>User-Agent:</quote> header so web servers can't tell
+    your browser type. Who's business is it anyway?
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Possible values:</term>
+  <listitem>
+   <para>
+    Any user defined string.
+   </para>
+  </listitem>
+ </varlistentry>
+ 
+ <varlistentry>
+  <term>Example usage:</term>
+  <listitem>
+    <literallayout>
+     <emphasis>{+hide-user-agent{Netscape 6.1 (X11; I; Linux 2.4.18 i686)}}</emphasis>
+     <emphasis>.msn.com</emphasis>
+    </literallayout>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+     Warning! This breaks many web sites that depend on this in order 
+     to determine how the target browser will respond to various 
+     requests. Use with caution.
+   </para>
+  </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+<!--   ~~~~~       New section      ~~~~~     -->
+<sect4 id="image">
+<title><emphasis>+image</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+  <term>Type:</term>
+  <!-- Boolean, Parameterized, Multi-value -->
+  <listitem>
+   <para>Boolean.</para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Typical uses:</term>
+  <listitem>
+   <para>
+    To define what <application>Privoxy</application> should treat 
+    automatically as an image.
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Possible values:</term>
+  <listitem>
+   <para>
+    N/A
+   </para>
+  </listitem>
+ </varlistentry>
+ 
+ <varlistentry>
+  <term>Example usage:</term>
+  <listitem>
+    <literallayout>
+     <emphasis>{+image}</emphasis>
+     <emphasis>/.*\.(gif|jpg|jpeg|png|bmp|ico)</emphasis>
+    </literallayout>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    This only has meaning if the URL (or pattern) also is
+    <quote>+block</quote>ed, in which case a <quote>blocked</quote> image can
+    be sent rather than a HTML page. (See <quote>+image-blocker{}</quote> below
+    for the control over what is actually sent.)    
+   </para>
+   <para>
+    There is little reason to change the default definition for this.
+   </para>
+  </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+
+<!--   ~~~~~       New section      ~~~~~     -->
+<sect4 id="image-blocker">
+<title><emphasis>+image-blocker</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+  <term>Type:</term>
+  <!-- Boolean, Parameterized, Multi-value -->
+  <listitem>
+   <para>Parameterized.</para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Typical uses:</term>
+  <listitem>
+   <para>
+    Decide what to do with URLs that end up tagged with both <quote>{+block}</quote>
+    and <quote>{+image}</quote>, e.g an advertisement.
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Possible values:</term>
+  <listitem>
+   <para>
+    There are four available options: <quote>-image-blocker</quote> will send a HTML
+    <quote>blocked</quote> page, usually resulting in a <quote>broken
+    image</quote> icon. <quote>+image-blocker{blank}</quote> will send a 1x1
+    transparent GIF image. <quote>+image-blocker{pattern}</quote> will send a
+    checkerboard type pattern (the default). And finally,
+    <quote>+image-blocker{http://xyz.com}</quote> will send a HTTP temporary
+    redirect to the specified image. This has the advantage of the icon being
+    being cached by the browser, which will speed up the display.
+   </para>
+  </listitem>
+ </varlistentry>
+ 
+ <varlistentry>
+  <term>Example usage:</term>
+  <listitem>
+    <literallayout>
+     <emphasis>{+image-blocker{blank}}</emphasis>
+     <emphasis>.example.com</emphasis>
+    </literallayout>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    If you want <emphasis>invisible</emphasis> ads, they need to be both
+    defined as <emphasis>images</emphasis> and <emphasis>blocked</emphasis>.
+    And then, <quote>image-blocker</quote> should be set to
+    <quote>blank</quote> for invisibility. Note you cannot treat HTML pages as
+    images in most cases. For instance, frames require an HTML page to display.
+    So a frame that is an ad, cannot be treated as an image. Forcing an
+    <quote>image</quote> in this situation just will not work.
+   </para>
+  </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+<!--   ~~~~~       New section      ~~~~~     -->
+<sect4 id="limit-connect">
+<title><emphasis>+limit-connect</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+  <term>Type:</term>
+  <!-- Boolean, Parameterized, Multi-value -->
+  <listitem>
+   <para>Parameterized.</para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Typical uses:</term>
+  <listitem>
+   <para>
+    By default, <application>Privoxy</application> only allows HTTP CONNECT
+    requests to port 443 (the standard, secure HTTPS port). Use 
+    <quote>+limit-connect</quote> to disable this altogether, or to allow 
+    more ports.
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Possible values:</term>
+  <listitem>
+   <para>
+    Any valid port number, or port number range.
+   </para>
+  </listitem>
+ </varlistentry>

  
  

- <listitem>
-  <para>  
-   Alternative spelling of <quote>+hide-referer</quote>.  It has the same
-   parameters, and can be freely mixed with, <quote>+hide-referer</quote>.
-   (<quote>referrer</quote> is the correct English spelling, however the HTTP
-   specification has a bug - it requires it to be spelled <quote>referer</quote>.) 
-  </para>
-  <para>
-   <literal>
-    <msgtext> 
-     <literallayout>
-  <emphasis>+hide-referrer{...}</emphasis>
-     </literallayout>
-    </msgtext> 
-   </literal>
-  </para>
- </listitem>
+ <varlistentry>
+  <term>Example usages:</term>
+  <listitem>
+   <!-- I had trouble getting the spacing to look right in my browser -->
+   <!-- I probably have the wrong font setup, bollocks. -->
+    <literallayout>
+     <emphasis>+limit-connect{443}</emphasis>                      # This is the default and need not be specified.
+     <emphasis>+limit-connect{80,443}</emphasis>                 # Ports 80 and 443 are OK.
+     <emphasis>+limit-connect{-3, 7, 20-100, 500-}</emphasis> # Port less than 3, 7, 20 to 100 and above 500 are OK.
+    </literallayout>
+  </listitem>
+ </varlistentry>

 
 

- <listitem>
-  <para>  
-   Change the <quote>User-Agent:</quote> header so web servers can't tell your
-   browser type.  Warning! This breaks many web sites.  Specify the
-   user-agent value you want. Example, pretend to be using Netscape on
-   Linux:
-  </para>
-  <para>
-   <literal>
-    <msgtext> 
-     <literallayout>
-  <emphasis>+hide-user-agent{Mozilla (X11; I; Linux 2.0.32 i586)}</emphasis>
-     </literallayout>
-    </msgtext> 
-   </literal>
-  </para>
- <!-- 
-  <para>
-   Or to identify yourself explicitly as a  <application>Privoxy</application> user:
-  </para>
-  <para>
-   <literal>
-    <msgtext> 
-     <literallayout>
-  <emphasis>+hide-user-agent{Privoxy/1.0}</emphasis>
-     </literallayout>
-    </msgtext> 
-   </literal>
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    The CONNECT methods exists in HTTP to allow access to secure websites
+    (https:// URLs) through proxies. It works very simply: the proxy connects
+    to the server on the specified port, and then short-circuits its
+    connections to the client <emphasis>and</emphasis> to the remote proxy.
+    This can be a big security hole, since CONNECT-enabled proxies can be
+    abused as TCP relays very easily.

   </para>
   </para>

-   (Don't change the version number from 1.0 - after all, why tell them?)
-  <para>
+  <para> 
+   If you want to allow CONNECT for more ports than this, or want to forbid
+   CONNECT altogether, you can specify a comma separated list of ports and
+   port ranges (the latter using dashes, with the minimum defaulting to 0 and
+   max to 65K).

   </para>
   <para>
   </para>
   <para>

-   <literal>
-    <msgtext> 
-     <literallayout>
-  <emphasis>+hide-user-agent{browser-type}</emphasis>
-     </literallayout>
-    </msgtext> 
-   </literal>
+   If you don't know what any of this means, there probably is no reason to 
+   change this one.

   </para>
   </para>

--->
- </listitem>
+  </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+<!--   ~~~~~       New section      ~~~~~     -->
+<sect4 id="no-compression">
+<title><emphasis>+no-compression</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+  <term>Type:</term>
+  <!-- Boolean, Parameterized, Multi-value -->
+  <listitem>
+   <para>Boolean.</para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Typical uses:</term>
+  <listitem>
+   <para>
+    Prevent the specified websites from compressing HTTP data.
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Possible values:</term>
+  <listitem>
+   <para>
+    N/A
+   </para>
+  </listitem>
+ </varlistentry>
+ 
+ <varlistentry>
+  <term>Example usage:</term>
+  <listitem>
+    <literallayout>
+     <emphasis>{+no-compression}</emphasis>
+     <emphasis>.example.com</emphasis>
+    </literallayout>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    Some websites do this, which can be a problem for
+    <application>Privoxy</application>, since <quote>+filter</quote>,
+    <quote>+no-popup</quote> and <quote>+gif-deanimate</quote> will not work
+    on compressed data. This will slow down connections to those websites,
+    though. Default typically is to turn <quote>no-compression</quote> on.
+   </para>
+  </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+<!--   ~~~~~       New section      ~~~~~     -->
+<sect4 id="no-cookies-keep">
+<title><emphasis>+no-cookies-keep</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+  <term>Type:</term>
+  <!-- Boolean, Parameterized, Multi-value -->
+  <listitem>
+   <para>Boolean.</para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Typical uses:</term>
+  <listitem>
+   <para>
+    Allow cookies for the current browser session only.
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Possible values:</term>
+  <listitem>
+   <para>
+    N/A
+   </para>
+  </listitem>
+ </varlistentry>
+ 
+ <varlistentry>
+  <term>Example usage:</term>
+  <listitem>
+    <literallayout>
+     <emphasis>{+no-cookies-keep}</emphasis>
+     <emphasis>.example.com</emphasis>
+    </literallayout>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    If websites set cookies, <quote>no-cookies-keep</quote> will make sure
+    they are erased when you exit and restart your web browser. This makes
+    profiling cookies useless, but won't break sites which require cookies so
+    that you can log in for transactions. This is generally turned on for all 
+    sites. Sometimes referred to as <quote>session cookies</quote>.
+   </para>
+  </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+
+<!--   ~~~~~       New section      ~~~~~     -->
+<sect4 id="no-cookies-read">
+<title><emphasis>+no-cookies-read</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+  <term>Type:</term>
+  <!-- Boolean, Parameterized, Multi-value -->
+  <listitem>
+   <para>Boolean.</para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Typical uses:</term>
+  <listitem>
+   <para>
+    Explicitly prevent the web server from reading any cookies on your 
+    system.
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Possible values:</term>
+  <listitem>
+   <para>
+    N/A
+   </para>
+  </listitem>
+ </varlistentry>
+ 
+ <varlistentry>
+  <term>Example usage:</term>
+  <listitem>
+    <literallayout>
+     <emphasis>{+no-cookies-read}</emphasis>
+     <emphasis>.example.com</emphasis>
+    </literallayout>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    Often used in conjunction with <quote>+no-cookies-set</quote> to 
+    disable persistant cookies completely.
+   </para>
+  </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+
+<!--   ~~~~~       New section      ~~~~~     -->
+<sect4 id="no-cookies-set">
+<title><emphasis>+no-cookies-set</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+  <term>Type:</term>
+  <!-- Boolean, Parameterized, Multi-value -->
+  <listitem>
+   <para>Boolean.</para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Typical uses:</term>
+  <listitem>
+   <para>
+    Explicitly block the web server from sending cookies to your 
+    system.
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Possible values:</term>
+  <listitem>
+   <para>
+    N/A
+   </para>
+  </listitem>
+ </varlistentry>
+ 
+ <varlistentry>
+  <term>Example usage:</term>
+  <listitem>
+    <literallayout>
+     <emphasis>{+no-cookies-set}</emphasis>
+     <emphasis>.example.com</emphasis>
+    </literallayout>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    Often used in conjunction with <quote>+no-cookies-read</quote> to 
+    disable persistant cookies completely.
+   </para>
+  </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+
+<!--   ~~~~~       New section      ~~~~~     -->
+<sect4 id="no-popup">
+<title><emphasis>+no-popup</emphasis></title>
+<anchor id="no-popups">
+
+<variablelist>
+ <varlistentry>
+  <term>Type:</term>
+  <!-- Boolean, Parameterized, Multi-value -->
+  <listitem>
+   <para>Boolean.</para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Typical uses:</term>
+  <listitem>
+   <para>
+    Stop those annoying JavaScript pop-up windows! 
+   </para>
+  </listitem>
+ </varlistentry>

 
 

- <listitem>
-  <para>  
-   Treat this URL as an image.  This only matters if it's also <quote>+block</quote>ed,
-   in which case a <quote>blocked</quote> image can be sent rather than a HTML page.
-   See <quote>+image-blocker{}</quote> below for the control over what is actually sent.
-   If you want <emphasis>invisible</emphasis> ads, they should be defined as 
-   <emphasis>images</emphasis> and <emphasis>blocked</emphasis>. And also, 
-   <quote>image-blocker</quote>  should be set to <quote>blank</quote>. Note you 
-   cannot treat HTML pages as images in most cases. For instance, frames 
-   require an HTML page to display. So a frame that is an ad, cannot be 
-   treated as an image. Forcing an <quote>image</quote> in this 
-   situation just will not work.
-  </para>
-  <para>
-   <literal>
-    <msgtext> 
-     <literallayout>
-  <emphasis>+image</emphasis>
-     </literallayout>
-    </msgtext> 
-   </literal>
-  </para>
- </listitem>
- 
- <listitem>
-  <para> Decides what to do with URLs that end up tagged with <quote>{+block
-  +image}</quote>, e.g an advertisement. There are four options.
-  <quote>-image-blocker</quote> will send a HTML <quote>blocked</quote> page,
-  usually resulting in a <quote>broken image</quote> icon.
-<!--   <quote>+image-blocker{logo}</quote> will send a -->
-<!--   <application>Privoxy</application> logo -->
-<!--   image. -->
-<quote>+image-blocker{blank}</quote> will send a 1x1 transparent GIF
-image. And finally, <quote>+image-blocker{http://xyz.com}</quote> will send a
-HTTP temporary redirect to the specified image. This has the advantage of the
-icon being being cached by the browser, which will speed up the display.
-<quote>+image-blocker{pattern}</quote> will send a checkerboard type pattern:
-<!-- , -->
-<!-- which scales better than the logo (which can get blocky if the browser -->
-<!-- enlarges it too much). -->
-  </para>
-  <para>
-   <literal>
-    <msgtext> 
-     <literallayout>
-<!--   <emphasis>+image-blocker{logo}</emphasis> -->
-  <emphasis>+image-blocker{blank}</emphasis>
-  <emphasis>+image-blocker{pattern}</emphasis>
-  <emphasis>+image-blocker{http://p.p/send-banner}</emphasis>
-     </literallayout>
-    </msgtext> 
-   </literal>
-  </para>
- </listitem>
- 
- <listitem>
-   <para> 
-   By default (i.e. in the absence of a <quote>+limit-connect</quote>
-   action), <application>Privoxy</application> will only allow CONNECT
-   requests to port 443, which is the standard port for https as a 
-   precaution.
-  </para>
+ <varlistentry>
+  <term>Possible values:</term>
+  <listitem>
+   <para>
+    N/A
+   </para>
+  </listitem>
+ </varlistentry>

  
  

-  <para>
-   The CONNECT methods exists in HTTP to allow access to secure websites
-   (https:// URLs) through proxies. It works very simply: the proxy
-   connects to the server on the specified port, and then short-circuits
-   its connections to the client <emphasis>and</emphasis> to the remote proxy.
-   This can be a big security hole, since CONNECT-enabled proxies can
-   be abused as TCP relays very easily.
-  </para>
-  
-  <para> 
-   If you want to allow CONNECT for more ports than this, or want to forbid
-   CONNECT altogether, you can specify a comma separated list of ports and
-   port ranges (the latter using dashes, with the minimum defaulting to 0 and
-   max to 65K):
-  </para>
+ <varlistentry>
+  <term>Example usage:</term>
+  <listitem>
+    <literallayout>
+     <emphasis>{+no-popup}</emphasis>
+     <emphasis>.example.com</emphasis>
+    </literallayout>
+  </listitem>
+ </varlistentry>

 
 

-  <para>
-   <literal>
-    <msgtext> 
-     <literallayout>
-  <emphasis>+limit-connect{443}                 # This is the default and need no be specified.</emphasis>
-  <emphasis>+limit-connect{80,443}              # Ports 80 and 443 are OK.</emphasis>
-  <emphasis>+limit-connect{-3, 7, 20-100, 500-} # Port less than 3, 7, 20 to 100</emphasis>
-  <emphasis>                                    #and above 500 are OK.</emphasis>
-     </literallayout>
-    </msgtext> 
-   </literal>
-  </para>
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    <quote>+no-popup</quote> uses a built in filter to disable pop-ups
+    that use the <literal>window.open()</literal> function, etc.
+   </para>
+   <para>
+    An alternate spelling is <quote>+no-popups</quote>, which is 
+    interchangeable.
+   </para>
+  </listitem>
+ </varlistentry>

 
 

- </listitem> 
- 
- <listitem>
-  <para>
-   <quote>+no-compression</quote> prevents the website from compressing the
-   data. Some websites do this, which can be a problem for
-   <application>Privoxy</application>, since <quote>+filter</quote>,
-   <quote>+no-popup</quote> and <quote>+gif-deanimate</quote> will not work on
-   compressed data. This will slow down connections to those websites,
-   though. Default is <quote>no-compression</quote> is turned on.
-  </para>
+</variablelist>
+</sect4>

 
 

-  <para>
-   <literal>
-    <msgtext> 
-     <literallayout>
-  <emphasis>+nocompression</emphasis>
-     </literallayout>
-    </msgtext> 
-   </literal>
-  </para>
- </listitem> 
- 
- <listitem>
-  <para>  
-   If the website sets cookies, <quote>no-cookies-keep</quote> will make sure
-   they are erased when you exit and restart your web browser. This makes
-   profiling cookies useless, but won't break sites which require cookies so
-   that you can log in for transactions. Default: on.
-  </para>
-  <para>
-   <literal>
-    <msgtext> 
-     <literallayout>
-  <emphasis>+no-cookies-keep</emphasis>
-     </literallayout>
-    </msgtext> 
-   </literal>
-  </para>
- </listitem>
- 
- <listitem>
-  <para>  
-   Prevent the website from reading cookies:
-  </para>
-  <para>
-   <literal>
-    <msgtext> 
-     <literallayout>
-  <emphasis>+no-cookies-read</emphasis>
-     </literallayout>
-    </msgtext> 
-   </literal>
-  </para>
- </listitem>
- 
- <listitem>
-  <para>  
-   Prevent the website from setting cookies:
-  </para>
-  <para>
-   <literal>
-    <msgtext> 
-     <literallayout>
-  <emphasis>+no-cookies-set</emphasis>
-     </literallayout>
-    </msgtext> 
-   </literal>
-  </para>
- </listitem>
- 
- <listitem>
-  <para>  
-   Filter the website through a built-in filter to disable those obnoxious 
-   JavaScript pop-up windows via window.open(), etc. The two alternative
-   spellings are equivalent.
-  </para>
-  <para>
-   <literal>
-    <msgtext> 
-     <literallayout>
-  <emphasis>+no-popup</emphasis>
-  <emphasis>+no-popups</emphasis>
-     </literallayout>
-    </msgtext> 
-   </literal>
-  </para>
- </listitem>
+
+<!--   ~~~~~       New section      ~~~~~     -->
+<sect4 id="vanilla-wafer">
+<title><emphasis>+vanilla-wafer</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+  <term>Type:</term>
+  <!-- Boolean, Parameterized, Multi-value -->
+  <listitem>
+   <para>Boolean.</para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Typical uses:</term>
+  <listitem>
+   <para>
+    Sends a cookie for every site stating that you do not accept any copyright
+    on cookies sent to you, and asking them not to track you.
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Possible values:</term>
+  <listitem>
+   <para>
+    N/A
+   </para>
+  </listitem>
+ </varlistentry>

  
  

- <listitem>
-  <para>  
-   This action only applies if you are using a <filename>jarfile</filename>
-   for saving cookies. It sends a cookie to every site stating that you do not
-   accept any copyright on cookies sent to you, and asking them not to track
-   you.  Of course, this is a (relatively) unique header they could use to
-   track you.
-  </para>
-  <para>
-   <literal>
-    <msgtext> 
-     <literallayout>
-  <emphasis>+vanilla-wafer</emphasis>
-     </literallayout>
-    </msgtext> 
-   </literal>
-  </para>
- </listitem>
+ <varlistentry>
+  <term>Example usage:</term>
+  <listitem>
+    <literallayout>
+     <emphasis>{+vanilla-wafer}</emphasis>
+     <emphasis>.example.com</emphasis>
+    </literallayout>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    This action only applies if you are using a <filename>jarfile</filename>
+    for saving cookies. Of course, this is a (relatively) unique header and 
+    could be used to track you.
+   </para>
+  </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>
+
+
+<!--   ~~~~~       New section      ~~~~~     -->
+<sect4 id="wafer">
+<title><emphasis>+wafer</emphasis></title>
+
+<variablelist>
+ <varlistentry>
+  <term>Type:</term>
+  <!-- Boolean, Parameterized, Multi-value -->
+  <listitem>
+   <para>Multi-value.</para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Typical uses:</term>
+  <listitem>
+   <para>
+    This allows you to send an arbitrary, user definable cookie.
+   </para>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Possible values:</term>
+  <listitem>
+   <para>
+    User specified cookie name and corresponding value.
+   </para>
+  </listitem>
+ </varlistentry>

  
  

- <listitem>
-  <para>  
-   This allows you to add an arbitrary cookie. It can be specified multiple
-   times in order to add as many cookies as you like.
-  </para>
-  <para>
-   <literal>
-    <msgtext> 
-     <literallayout>
-  <emphasis>+wafer{name=value}</emphasis>
-     </literallayout>
-    </msgtext> 
-   </literal>
-  </para>
- </listitem>
+ <varlistentry>
+  <term>Example usage:</term>
+  <listitem>
+    <literallayout>
+     <emphasis>{+wafer{name=value}}</emphasis>
+     <emphasis>.example.com</emphasis>
+    </literallayout>
+  </listitem>
+ </varlistentry>
+
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+   <para>
+    This can be specified multiple times in order to add as many cookies as you
+    like.
+   </para>
+  </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect4>

 
 

- </itemizedlist>
-</para>

 
 

+<!--   ~~~~~       New section      ~~~~~     -->
+<sect4 id="act-examples" renderas="sect3">
+<title>Actions Examples</title>

 <para>
 <para>

- The meaning of any of the above is reversed by preceding the action with a 
- <quote>-</quote>, in place of the <quote>+</quote>.
+ Note that the meaning of any of the above examples is reversed by preceding
+ the action with a <quote>-</quote>, in place of the <quote>+</quote>. Also, 
+ that some actions are turned on in the default section of the actions file, 
+ and require little to no additional configuration. These are just <quote>on</quote>.
+ Some actions that are turned on the default section do typically require
+ exceptions to be listed in the lower sections of actions file.

 </para>
 
 <para>
 </para>
 
 <para>


@@ -3226,10 +4040,12 @@ icon being being cached by the browser, which will speed up the display.
  # Turn off all persistent cookies
  { +no-cookies-read }
  { +no-cookies-set }
  # Turn off all persistent cookies
  { +no-cookies-read }
  { +no-cookies-set }

+ 

  # Allow cookies for this browser session ONLY
  { +no-cookies-keep }
 
  # Exceptions to the above, sites that benefit from persistent cookies
  # Allow cookies for this browser session ONLY
  { +no-cookies-keep }
 
  # Exceptions to the above, sites that benefit from persistent cookies

+ # that saved from one browser session to the next.

  { -no-cookies-read }
  { -no-cookies-set }
  { -no-cookies-keep }
  { -no-cookies-read }
  { -no-cookies-set }
  { -no-cookies-keep }


@@ -3293,9 +4109,9 @@ icon being being cached by the browser, which will speed up the display.
 
 <para>
  Now some URLs that we want <quote>blocked</quote> (normally generates 
 
 <para>
  Now some URLs that we want <quote>blocked</quote> (normally generates 

- the <quote>blocked</quote> banner). Many of these use regular expressions
- that will expand to match multiple URLs:
-</para>
+ the <quote>blocked</quote> banner). Many of these use 
+ <link linkend="regex">regular expressions</link> that will expand to match
+ multiple URLs: </para>

 
 <para>
  <literal>
 
 <para>
  <literal>


@@ -3359,6 +4175,7 @@ icon being being cached by the browser, which will speed up the display.
  for all sites. See the <link linkend="ACTIONSANAT">Appendix</link>
  for a brief example on troubleshooting actions.
 </para>
  for all sites. See the <link linkend="ACTIONSANAT">Appendix</link>
  for a brief example on troubleshooting actions.
 </para>

+</sect4>

 
 </sect3>
 
 
 </sect3>
 


@@ -3424,14 +4241,14 @@ icon being being cached by the browser, which will speed up the display.
  .windowsupdate.microsoft.com
  .nytimes.com
 
  .windowsupdate.microsoft.com
  .nytimes.com
 

- # Shopping sites - still want to block ads.
+ # Shopping sites - but we still want to block ads.

  {shop}
  .quietpc.com
  .worldpay.com   # for quietpc.com
  .jungle.com
  .scan.co.uk
 
  {shop}
  .quietpc.com
  .worldpay.com   # for quietpc.com
  .jungle.com
  .scan.co.uk
 

- # These shops require pop-ups
+ # These shops require pop-ups also 

  {shop -no-popups}
  .dabs.com
  .overclockers.co.uk
  {shop -no-popups}
  .dabs.com
  .overclockers.co.uk


@@ -3743,14 +4560,18 @@ Requests</title>
   <emphasis>\</emphasis> - The <quote>escape</quote> character denotes that
   the following character should be taken literally. This is used where one of the 
   special characters (e.g. <quote>.</quote>) needs to be taken literally and
   <emphasis>\</emphasis> - The <quote>escape</quote> character denotes that
   the following character should be taken literally. This is used where one of the 
   special characters (e.g. <quote>.</quote>) needs to be taken literally and

-  not as a special meta-character.
+  not as a special meta-character. Example: <quote>example\.com</quote>, makes 
+  sure the period is recognized only as a period (and not expanded to its 
+  metacharacter meaning of any single character).

  </member>
 </simplelist></para>
 
 <para><simplelist>
  <member>
   <emphasis>[]</emphasis> - Characters enclosed in brackets will be matched if
  </member>
 </simplelist></para>
 
 <para><simplelist>
  <member>
   <emphasis>[]</emphasis> - Characters enclosed in brackets will be matched if

-  any of the enclosed characters are encountered.
+  any of the enclosed characters are encountered. For instance, <quote>[0-9]</quote>
+  matches any numeric digit (zero through nine). As an example, we can combine 
+  this with <quote>+</quote> to match any digit one of more times: <quote>[0-9]+</quote>.

  </member>
 </simplelist></para>
 
  </member>
 </simplelist></para>
 


@@ -3765,7 +4586,10 @@ Requests</title>
  <member>
   <emphasis>|</emphasis> - The <quote>bar</quote> character works like an
   <quote>or</quote> conditional statement. A match is successful if the
  <member>
   <emphasis>|</emphasis> - The <quote>bar</quote> character works like an
   <quote>or</quote> conditional statement. A match is successful if the

-  sub-expression on either side of <quote>|</quote> matches.
+  sub-expression on either side of <quote>|</quote> matches. As an example:
+  <quote>/(this|that) example/</quote> uses grouping and the bar character 
+  and would match either <quote>this example</quote> or <quote>that
+  example</quote>, and nothing else.

  </member>
 </simplelist></para>
 
  </member>
 </simplelist></para>
 


@@ -3773,7 +4597,7 @@ Requests</title>
  <member>
   <emphasis>s/string1/string2/g</emphasis> - This is used to rewrite strings of text. 
   <quote>string1</quote> is replaced by <quote>string2</quote> in this
  <member>
   <emphasis>s/string1/string2/g</emphasis> - This is used to rewrite strings of text. 
   <quote>string1</quote> is replaced by <quote>string2</quote> in this

-  example.
+  example. There must of course be a match on <quote>string1</quote> first.

  </member>
 </simplelist></para>
 
  </member>
 </simplelist></para>
 


@@ -4022,7 +4846,7 @@ Requests</title>
 </para>
 
 <para>
 </para>
 
 <para>

- These may be bookmarked for quick reference.
+ These may be bookmarked for quick reference. See next.

 
 </para>
 
 
 </para>
 


@@ -4108,11 +4932,22 @@ Requests</title>
  is causing us a problem inadvertently. It can be a little daunting to look at
  the actions and filters files themselves, since they tend to be filled with
  <quote>regular expressions</quote> whose consequences are not always 
  is causing us a problem inadvertently. It can be a little daunting to look at
  the actions and filters files themselves, since they tend to be filled with
  <quote>regular expressions</quote> whose consequences are not always 

- so obvious. <application>Privoxy</application> provides the 
+ so obvious. 
+</para>
+
+<para>
+ One quick test to see if <application>Privoxy</application> is causing a problem 
+ or not, is to disable it temporarily. This should be the first troubleshooting 
+ step. See <link linkend="bookmarklets">the Bookmarklets</link> section on a quick 
+ and easy way to do this (be sure to flush caches afterwards!).
+</para>
+
+<para>
+ <application>Privoxy</application> also provides the 

  <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
  page that can show us very specifically how <application>actions</application>
  are being applied to any given URL. This is a big help for troubleshooting.
  <ulink url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>
  page that can show us very specifically how <application>actions</application>
  are being applied to any given URL. This is a big help for troubleshooting.

- </para>
+</para>

 
 <para>
  First, enter one URL (or partial URL) at the prompt, and then
 
 <para>
  First, enter one URL (or partial URL) at the prompt, and then


@@ -4395,6 +5230,37 @@ Requests</title>
  Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
  $Log: user-manual.sgml,v $
  Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
  $Log: user-manual.sgml,v $

+ Revision 1.88  2002/04/23 05:37:54  hal9
+ Add AmigaOS install stuff.
+
+ Revision 1.87  2002/04/23 02:53:15  david__schmidt
+ Updated OSX installation section
+ Added a few English tweaks here an there
+
+ Revision 1.86  2002/04/21 01:46:32  hal9
+ Re-write actions section.
+
+ Revision 1.85  2002/04/18 21:23:23  hal9
+ Fix ugly typo (mine).
+
+ Revision 1.84  2002/04/18 21:17:13  hal9
+ Spell Redhat correctly (ie Red Hat). A few minor grammar corrections.
+
+ Revision 1.83  2002/04/18 18:21:12  oes
+ Added RPM install detail
+
+ Revision 1.82  2002/04/18 12:04:50  oes
+ Cosmetics
+
+ Revision 1.81  2002/04/18 11:50:24  oes
+ Extended Install section - needs fixing by packagers
+
+ Revision 1.80  2002/04/18 10:45:19  oes
+ Moved text to buildsource.sgml, renamed some filters, details
+
+ Revision 1.79  2002/04/18 03:18:06  hal9
+ Spellcheck, and minor touchups.
+

  Revision 1.78  2002/04/17 18:04:16  oes
  Proofreading part 2
 
  Revision 1.78  2002/04/17 18:04:16  oes
  Proofreading part 2