Further proofread & reactivated short build instructions

diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml
index 06daeb7..b081757 100644 (file)
--- a/doc/source/user-manual.sgml
+++ b/doc/source/user-manual.sgml
@@ -25,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.100 2002/04/29 03:05:55 hal9 Exp $
+ $Id: user-manual.sgml,v 1.101 2002/05/03 03:58:30 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/


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

-<pubdate>$Id: user-manual.sgml,v 1.100 2002/04/29 03:05:55 hal9 Exp $</pubdate>
+<pubdate>$Id: user-manual.sgml,v 1.101 2002/05/03 03:58:30 hal9 Exp $</pubdate>

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


@@ -147,39 +147,28 @@
  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
  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>. For installing and compiling the source code, please look 
- into our Developer Manual.
+ Page</ulink>.

 </para>
 
 </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
- version directly from <ulink url="http://sourceforge.net/cvs/?group_id=11118">the
- CVS repository</ulink> or simply download <ulink
- url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.gz">the nightly CVS
- tarball.</ulink> Again, we refer you to the Developer Manual.
-</para>
-
-<!-- Include supported.sgml boilerplate -->
- &supported; 
-<!-- end boilerplate -->
-

 <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>
  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>

  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> section
  below.
 </para>
 
  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> section
  below.
 </para>
 

+<!--   ~~~~~       New section      ~~~~~     --> 
+<sect2 id="installation-packages"><title>Binary Packages</title>
+<para>
+How to install the binary packages depends on your operating system:
+</para>
+

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

-<sect2 id="installation-pack-rpm"><title>Red Hat 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>,
 
 <para>
  RPMs can be installed with <literal>rpm -Uvh privoxy-&p-version;-1.rpm</literal>,


@@ -207,17 +196,17 @@ automatically start Privoxy in the boot process.
  Otherwise, RPM will try to remove <application>Junkbuster</application>
  automatically, before installing <application>Privoxy</application>.
 </para>
  Otherwise, RPM will try to remove <application>Junkbuster</application>
  automatically, before installing <application>Privoxy</application>.
 </para>

-</sect2>
+</sect3>

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

-<sect2 id="installation-deb"><title>Debian</title>
+<sect3 id="installation-deb"><title>Debian</title>

 <para>
  FIXME.
 </para>
 <para>
  FIXME.
 </para>

-</sect2>
+</sect3>

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

-<sect2 id="installation-pack-win"><title>Windows</title>
+<sect3 id="installation-pack-win"><title>Windows</title>

 
 <para>
  Just double-click the installer, which will guide you through
 
 <para>
  Just double-click the installer, which will guide you through


@@ -225,20 +214,20 @@ automatically start Privoxy in the boot process.
  in the same directory as you installed Privoxy in. We do not
  use the registry of Windows. 
 </para>
  in the same directory as you installed Privoxy in. We do not
  use the registry of Windows. 
 </para>

-</sect2>
+</sect3>

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

-<sect2 id="installation-pack-bintgz"><title>Solaris, NetBSD, FreeBSD, HP-UX</title>
+<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>
 
 <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>

-</sect2>
+</sect3>

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

-<sect2 id="installation-os2"><title>OS/2</title>
+<sect3 id="installation-os2"><title>OS/2</title>

 
 <para>
  First, make sure that no previous installations of
 
 <para>
  First, make sure that no previous installations of


@@ -258,10 +247,10 @@ automatically start Privoxy in the boot process.
  The directory you choose to install <application>Privoxy</application>
  into will contain all of the configuration files.
 </para>
  The directory you choose to install <application>Privoxy</application>
  into will contain all of the configuration files.
 </para>

-</sect2>
+</sect3>

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

-<sect2 id="installation-mac"><title>Max OSX</title>
+<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,
 <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,


@@ -273,10 +262,10 @@ automatically start Privoxy in the boot process.
  automatically on system bring-up via
  <literal>/System/Library/StartupItems/Privoxy</literal>.
 </para>
  automatically on system bring-up via
  <literal>/System/Library/StartupItems/Privoxy</literal>.
 </para>

-</sect2>
+</sect3>

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

-<sect2 id="installation-amiga"><title>AmigaOS</title>
+<sect3 id="installation-amiga"><title>AmigaOS</title>

 <para>
  Copy and then unpack the <filename>lha</filename> archive to a suitable location. 
  All necessary files will be installed into <application>Privoxy</application>
 <para>
  Copy and then unpack the <filename>lha</filename> archive to a suitable location. 
  All necessary files will be installed into <application>Privoxy</application>


@@ -292,7 +281,35 @@ automatically start Privoxy in the boot process.
  TCP/IP stack (just ignore the harmless warning your TCP/IP stack may display that
  <application>Privoxy</application> is still running).
 </para>
  TCP/IP stack (just ignore the harmless warning your TCP/IP stack may display that
  <application>Privoxy</application> is still running).
 </para>

+</sect3>

 </sect2>
 </sect2>

+
+<!--   ~~~~~       New section      ~~~~~     -->
+<sect2 id="installation-source"><title>Building from Source</title>
+
+<para>
+ The most convenient way to obtain the <application>Privoxy</application> sources
+ is to download the source tarball from our <ulink url="http://sf.net/projects/ijbswa/">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
+ version directly from <ulink url="http://sourceforge.net/cvs/?group_id=11118">the
+ CVS repository</ulink> or simply download <ulink
+ url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.gz">the nightly CVS
+ tarball.</ulink>
+</para>
+
+<!-- include buildsource.sgml boilerplate: -->
+&buildsource;
+<!-- end boilerplate -->
+
+
+
+</sect2>
+

 </sect1>
 
 <!--  ~  End section  ~  -->
 </sect1>
 
 <!--  ~  End section  ~  -->


@@ -301,14 +318,17 @@ automatically start Privoxy in the boot process.
 <sect1 id="upgradersnote">
 <title>Note to Upgraders</title>
 <para>
 <sect1 id="upgradersnote">
 <title>Note to Upgraders</title>
 <para>

- There are very significant changes from older versions of 
- <application>Junkbuster</application> to the current
- <application>Privoxy</application>. Configuration is substantially 
- changed. <application>Junkbuster 2.0.x</application> and earlier 
- configuration files will not migrate. The functionality of the old
- <filename>blockfile</filename>, <filename>cookiefile</filename> and
- <filename>imagelist</filename>, are now combined into the
- <ulink url="actions-file.html"><quote>actions files</quote></ulink>.  
+ There are very significant changes from earlier 
+ <application>Junkbuster</application> versions to the current
+ <application>Privoxy</application>. The number, names, syntax, and
+ purposes of configuration files have substantially  changed.
+ <application>Junkbuster 2.0.x</application> configuration
+ files will not migrate, <application>Junkbuster 2.9.x</application>
+ and <application>Privoxy</application> configurations will need to be
+ ported. The functionalities of the old <filename>blockfile</filename>,
+ <filename>cookiefile</filename> and <filename>imagelist</filename> 
+ are now combined into the <ulink url="actions-file.html"><quote>actions
+ files</quote></ulink>.  

  <filename>default.action</filename>, is the main actions file. Local
  exceptions should best be put into <filename>user.action</filename>.
 </para>
  <filename>default.action</filename>, is the main actions file. Local
  exceptions should best be put into <filename>user.action</filename>.
 </para>


@@ -759,8 +779,8 @@ must find a better place for this paragraph
 
 <para>
  This should be self-explanatory. Note the first item leads to an editor for the
 
 <para>
  This should be self-explanatory. Note the first item leads to an editor for the

- <quote>actions list</quote>, which is where the ad, banner, cookie,
- and URL blocking magic is configured as well as other advanced features of
+ <link linkend="actions-file">actions files</link>, which is where the ad, banner,
+ cookie, and URL blocking magic is configured as well as other advanced features of

  <application>Privoxy</application>. This is an easy way to adjust various
  aspects of <application>Privoxy</application> configuration. The actions
  file, and other configuration files, are explained in detail below. 
  <application>Privoxy</application>. This is an easy way to adjust various
  aspects of <application>Privoxy</application> configuration. The actions
  file, and other configuration files, are explained in detail below. 


@@ -771,7 +791,8 @@ must find a better place for this paragraph
  have problems with your current actions and filters. You can in fact use
  it as a test to see whether it is <application>Privoxy</application> 
  causing the problem or not. <application>Privoxy</application> continues 
  have problems with your current actions and filters. You can in fact use
  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
+ to run as a proxy in this case, but all manipulation is disabled, i.e.
+ <application>Privoxy</application> acts like a normal forwarding proxy. There

  is even a toggle <link linkend="bookmarklets">Bookmarklet</link> 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.


@@ -808,7 +829,7 @@ must find a better place for this paragraph
 
   <listitem>
    <para>
 
   <listitem>
    <para>

-     The main configuration file is named <link linkend="config">config</link>
+     The <link linkend="config">main configuration file</link> is named <filename>config</filename>

      on Linux, Unix, BSD, OS/2, and AmigaOS and <filename>config.txt</filename>
      on Windows. This is a required file.
    </para>
      on Linux, Unix, BSD, OS/2, and AmigaOS and <filename>config.txt</filename>
      on Windows. This is a required file.
    </para>


@@ -816,25 +837,29 @@ must find a better place for this paragraph
 
   <listitem>
    <para>
 
   <listitem>
    <para>

-    <filename>default.action</filename> (the main <link linkend="actions-file">actions file</link>) is used to define
-    the default settings for various <quote>actions</quote> relating to images, banners, 
-    pop-ups, access restrictions, banners and cookies.
+    <filename>default.action</filename> (the main <link linkend="actions-file">actions file</link>)
+    is used to define which <quote>actions</quote> relating to banner-blocking, images, pop-ups,
+    content modification, cookie handling etc should be applied by default. It also defines many
+    exceptions (both positive and negative) from this default set of actions that enable 
+    <application>Privoxy</application> to selectively eliminate the junk, and only the junk, on
+    as many websites as possible.

    </para>
    <para>
     Multiple actions files may be defined in <filename>config</filename>. These 
     are processed in the order they are defined. Local customizations and locally 
    </para>
    <para>
     Multiple actions files may be defined in <filename>config</filename>. These 
     are processed in the order they are defined. Local customizations and locally 

-    preferred exceptions to the default policies as defined in
-    <filename>default.action</filename> are probably best applied in
-    <filename>user.action</filename>, which should be preserved across
-    upgrades. <filename>standard.action</filename> is also included. This is mostly 
-    for <application>Privoxy's</application> internal use.
+    preferred exceptions to the default policies  as defined in
+    <filename>default.action</filename> (which you will most propably want
+    to define sooner or later) are probably best applied in
+    <filename>user.action</filename>, where you can preserve them across
+    upgrades. <filename>standard.action</filename> is for
+    <application>Privoxy's</application> internal use.

    </para>
    <para>    
     There is also a web based editor that can be accessed from
     <ulink
    </para>
    <para>    
     There is also a web based editor that can be accessed from
     <ulink

-    url="http://config.privoxy.org/show-status/">http://config.privoxy.org/show-status/</ulink>
+    url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>

     (Shortcut: <ulink
     (Shortcut: <ulink

-    url="http://p.p/show-status/">http://p.p/show-status/</ulink>) for the
+    url="http://p.p/show-status">http://p.p/show-status</ulink>) for the

     various actions files. 
    </para>
   </listitem> 
     various actions files. 
    </para>
   </listitem> 


@@ -854,7 +879,7 @@ must find a better place for this paragraph
 
 <para>
  All files use the <quote><literal>#</literal></quote> character to denote a
 
 <para>
  All files use the <quote><literal>#</literal></quote> character to denote a

- comment (the rest of the line will be ignored) angd understand line continuation
+ comment (the rest of the line will be ignored) and understand line continuation

  through placing a backslash ("<literal>\</literal>") as the very last character
  in a line. If the <literal>#</literal> is preceded by a backslash, it looses
  its special function. Placing a <literal>#</literal> in front of an otherwise
  through placing a backslash ("<literal>\</literal>") as the very last character
  in a line. If the <literal>#</literal> is preceded by a backslash, it looses
  its special function. Placing a <literal>#</literal> in front of an otherwise


@@ -909,8 +934,7 @@ must find a better place for this paragraph
  <literal>
   <msgtext> 
    <literallayout>
  <literal>
   <msgtext> 
    <literallayout>

-  <emphasis>confdir /etc/privoxy</emphasis>
-   </literallayout>
+  <emphasis>confdir /etc/privoxy</emphasis></literallayout>

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


@@ -952,61 +976,6 @@ must find a better place for this paragraph
  be modified, such as log files.
 </para>
 
  be modified, such as log files.
 </para>
 

-<sect3 renderas="sect4" id="user-manual"><title>user-manual</title>
-<variablelist>
- <varlistentry>
-  <term>Specifies:</term>
-  <listitem>
-   <para>
-    Location of the <application>Privoxy</application> User Manual.
-   </para>
-  </listitem>
- </varlistentry>
- <varlistentry>
-  <term>Type of value:</term>
-  <listitem>
-   <para>A fully qualified URI</para>
-  </listitem>
- </varlistentry>
- <varlistentry>
-  <term>Default value:</term>
-  <listitem>
-   <para><ulink url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/user-manual/</ulink></para>
-  </listitem>
- </varlistentry>
- <varlistentry>
-  <term>Effect if unset:</term>
-  <listitem>
-   <para>
-    The default will be used.
-   </para>
-  </listitem>
- </varlistentry>
- <varlistentry>
-  <term>Notes:</term>
-  <listitem>
-   <para>
-    The User Manual is used for help hints from some of the internal CGI pages. 
-    It is normally packaged with the binary distributions, and would make more 
-    sense to have this pointed at a locally installed copy.
-   </para>
-   <para>
-    A more useful example (Unix):
-   </para>
-  <para> 
-   &nbsp;&nbsp;<emphasis>user-manual&nbsp;&nbsp;file:///usr/share/doc/privoxy-&p-version;/user-manual/</emphasis>
-  </para>
-  <warning>
-   <para>
-    If this option is defined, it must come first! It is needed before the rest of 
-    <filename>config</filename> is read.
-   </para>
-  </warning>
-  </listitem>
- </varlistentry>
-</variablelist>
-</sect3>
-

 <sect3 renderas="sect4" id="confdir"><title>confdir</title>
 
 <variablelist>
 <sect3 renderas="sect4" id="confdir"><title>confdir</title>
 
 <variablelist>


@@ -1106,14 +1075,14 @@ actionsfile
   <term>Specifies:</term>
   <listitem>
    <para>
   <term>Specifies:</term>
   <listitem>
    <para>

-    The <link linkend="actions">actions</link> file(s) to use
+    The <link linkend="actions-file">actions file(s)</link> to use

    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term>Type of value:</term>
   <listitem>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term>Type of value:</term>
   <listitem>

-   <para>File name, relative to <literal>confdir</literal></para>
+   <para>File name, relative to <literal>confdir</literal>, without the <literal>.action</literal> suffix</para>

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


@@ -1121,7 +1090,7 @@ actionsfile
   <listitem>
    <simplelist>
     <member>
   <listitem>
    <simplelist>
     <member>

-     <msgtext><literallayout>  standard     # Internal purposes, recommended not editing</literallayout></msgtext>
+     <msgtext><literallayout>  standard     # Internal purposes, no editing recommended</literallayout></msgtext>

     </member>
     <member>
      <msgtext><literallayout>  default      # Main actions file</literallayout></msgtext>
     </member>
     <member>
      <msgtext><literallayout>  default      # Main actions file</literallayout></msgtext>


@@ -1192,7 +1161,7 @@ actionsfile
    <para>
     No textual content filtering takes place, i.e. all
     <literal>+filter{<replaceable class="parameter">name</replaceable>}</literal>
    <para>
     No textual content filtering takes place, i.e. all
     <literal>+filter{<replaceable class="parameter">name</replaceable>}</literal>

-    actions in the actions files are turned off
+    actions in the actions files are turned neutral.

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


@@ -1372,7 +1341,6 @@ actionsfile
  </varlistentry>
 </variablelist>
 </sect3>
  </varlistentry>
 </variablelist>
 </sect3>

-

 </sect2>
 
 <!--  ~  End section  ~  -->
 </sect2>
 
 <!--  ~  End section  ~  -->


@@ -1390,6 +1358,72 @@ actionsfile
     you, what you block and why you do that, your policies etc.
    </para>
 
     you, what you block and why you do that, your policies etc.
    </para>
 

+<sect3 renderas="sect4" id="user-manual"><title>user-manual</title>
+<variablelist>
+ <varlistentry>
+  <term>Specifies:</term>
+  <listitem>
+   <para>
+    Location of the <application>Privoxy</application> User Manual.
+   </para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Type of value:</term>
+  <listitem>
+   <para>A fully qualified URI</para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Default value:</term>
+  <listitem>
+   <para><emphasis>Unset</emphasis></para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Effect if unset:</term>
+  <listitem>
+   <para>
+    <ulink url="http://www.privoxy.org/user-manual/">http://www.privoxy.org/<replaceable class="parameter">version</replaceable>/user-manual/</ulink>
+    will be used, where <replaceable class="parameter">version</replaceable> is the <application>Privoxy</application> version.
+   </para>
+  </listitem>
+ </varlistentry>
+ <varlistentry>
+  <term>Notes:</term>
+  <listitem>
+    <para>
+    The User Manual URI is used for help links from some of the internal CGI pages. 
+    The manual itself is normally packaged with the binary distributions, so you propably want
+    to set this to a locally installed copy. For multi-user setups, you could provide a copy on
+    a local webserver for all your users and use the corresponding URL here.
+   </para>
+   <para>
+    Examples:
+   </para>
+  <para>
+   Unix, in local filesystem:
+  </para>
+  <para>
+   <screen>user-manual&nbsp;&nbsp;file:///usr/share/doc/privoxy-&p-version;/user-manual/</screen>
+  </para>
+  <para>
+   Any platform, on local webserver (called <quote>local-webserver</quote>):
+  </para>
+  <para>
+   <screen>user-manual&nbsp;&nbsp;http://local-webserver/privoxy-user-manual/</screen>
+  </para>
+  <warning>
+   <para>
+     If set, this option should be <emphasis>the first option in the config file</emphasis>, because
+     it is used while the config file is being read.
+   </para>
+  </warning>     
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+

 <sect3 renderas="sect4" id="trust-info-url"><title>trust-info-url</title>
 
 <variablelist>
 <sect3 renderas="sect4" id="trust-info-url"><title>trust-info-url</title>
 
 <variablelist>


@@ -2571,7 +2605,7 @@ forward-socks4 and forward-socks4a</title>
 
 <para>
  The actions files are used to define what actions
 
 <para>
  The actions files are used to define what actions

- <application>Privoxy</application> takes for which URLs, and thus determines
+ <application>Privoxy</application> takes for which URLs, and thus determine

  how ad images, cookies and various other aspects of HTTP content and
  transactions are handled, and on which sites (or even parts thereof). There 
  are three such files included with <application>Privoxy</application> (as of 
  how ad images, cookies and various other aspects of HTTP content and
  transactions are handled, and on which sites (or even parts thereof). There 
  are three such files included with <application>Privoxy</application> (as of 


@@ -2585,7 +2619,9 @@ forward-socks4 and forward-socks4a</title>
       <filename>standard.action</filename> - is used by the web based editor, 
       to set various pre-defined sets of rules for the default actions section
       in <filename>default.action</filename>. These have increasing levels of
       <filename>standard.action</filename> - is used by the web based editor, 
       to set various pre-defined sets of rules for the default actions section
       in <filename>default.action</filename>. These have increasing levels of

-      aggressiveness. It is not recommend to edit this file.
+      aggressiveness <emphasis>and have no influence on your browsing unless
+      you select them explicitly in the editor</emphasis>. It is not recommend
+      to edit this file.

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


@@ -2618,11 +2654,18 @@ forward-socks4 and forward-socks4a</title>
 </para>
 
 <para>
 </para>
 
 <para>

- An actions file typically has sections. Near the top, <quote>aliases</quote> are 
- optionally defined (discussed <ulink
- url="actions-file.html#ALIASES">below</ulink>), then the default set of rules
- which will apply universally to all sites and pages. And then below that,
- exceptions to the defined universal policies. 
+ An actions file typically has multiple sections. If you want to use
+ <quote>aliases</quote> in an actions file, you have to place the (optional)
+ <link linkend="aliases">alias section</link> at the top of that file.
+ Then comes the default set of rules which will apply universally to all
+ sites and pages (be <emphasis>very careful</emphasis> with using such a
+ universal set in <filename>user.action</filename> or any other actions file after 
+ <filename>default.action</filename>, because it will override the result
+ from consulting any previous file). And then below that,
+ exceptions to the defined universal policies. You can regard
+ <filename>user.action</filename> as an appendix to <filename>default.action</filename>,
+ with the advantage that is a separate file, which makes preserving your
+ personal settings across <application>Privoxy</application> upgrades easier.

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


@@ -2630,7 +2673,8 @@ forward-socks4 and forward-socks4a</title>
  just some obnoxious URL that you would rather not see. Cookies can be accepted
  or rejected, or accepted only during the current browser session (i.e. not
  written to disk), content can be modified, JavaScripts tamed, user-tracking
  just some obnoxious URL that you would rather not see. Cookies can be accepted
  or rejected, or accepted only during the current browser session (i.e. not
  written to disk), content can be modified, JavaScripts tamed, user-tracking

- fooled, and much more. See below for a complete list of actions.
+ fooled, and much more. See below for a <link linkend="actions">complete list
+ of actions</link>.

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


@@ -2661,14 +2705,18 @@ forward-socks4 and forward-socks4a</title>
 <sect2>
 <title>How to Edit</title>
 <para>
 <sect2>
 <title>How to Edit</title>
 <para>

- The easiest way to edit the <quote>actions</quote> files is with a browser by
+ The easiest way to edit the actions files is with a browser by

  using our browser-based editor, which can be reached from <ulink
  url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.
  using our browser-based editor, which can be reached from <ulink
  url="http://config.privoxy.org/show-status">http://config.privoxy.org/show-status</ulink>.

+ The editor allows both fine-grained control over every single feature on a
+ per-URL basis, and easy choosing from wholesale sets of defaults like
+ <quote>Cautious</quote>, <quote>Medium</quote> or <quote>Advanced</quote>.

 </para>
 
 <para>
  If you prefer plain text editing to GUIs, you can of course also directly edit the
 </para>
 
 <para>
  If you prefer plain text editing to GUIs, you can of course also directly edit the

- the actions files.
+ the actions files. Look at <filename>default.action</filename> which is richly
+ commented.

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


@@ -2686,7 +2734,7 @@ forward-socks4 and forward-socks4a</title>
 
 <para>
  To determine which actions apply to a request, the URL of the request is
 
 <para>
  To determine which actions apply to a request, the URL of the request is

- compared to all patterns in this file. Every time it matches, the list of
+ compared to all patterns in each action file file. Every time it matches, the list of

  applicable actions for the URL is incrementally updated, using the heading
  of the section in which the pattern is located. If multiple matches for
  the same URL set the same action differently, the last match wins. If not, 
  applicable actions for the URL is incrementally updated, using the heading
  of the section in which the pattern is located. If multiple matches for
  the same URL set the same action differently, the last match wins. If not, 


@@ -2697,7 +2745,7 @@ forward-socks4 and forward-socks4a</title>
 </para>
 
 <para>
 </para>
 
 <para>

- You can trace this process by visiting <ulink
+ You can trace this process for any given URL by visiting <ulink

  url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>.
 </para>
 
  url="http://config.privoxy.org/show-url-info">http://config.privoxy.org/show-url-info</ulink>.
 </para>
 


@@ -2905,73 +2953,84 @@ forward-socks4 and forward-socks4a</title>
  All actions are disabled by default, until they are explicitly enabled
  somewhere in an actions file. Actions are turned on if preceded with a
  <quote>+</quote>, and turned off if preceded with a <quote>-</quote>. So a
  All actions are disabled by default, until they are explicitly enabled
  somewhere in an actions file. Actions are turned on if preceded with a
  <quote>+</quote>, and turned off if preceded with a <quote>-</quote>. So a

- <quote>+action</quote> means <quote>do that action</quote>, e.g.
- <quote>+block</quote> means please <quote>block the following URL
- patterns</quote>. 
+ <literal>+action</literal> means <quote>do that action</quote>, e.g.
+ <literal>+block</literal> means <quote>please block URLs that match the
+ following patterns</quote>, and <literal>-block</literal> means <quote>don't
+ block URLs that match the following patterns, even if <literal>+block</literal>
+ previously applied.</quote>
+
+</para>
+
+<para> 
+ Again, actions are invoked by placing them on a line, enclosed in curly braces and
+ separated by whitespace, like in 
+ <literal>{+some-action -some-other-action{some-parameter}}</literal>,
+ followed by a list of URL patterns, one per line, to which they apply.
+ Together, the actions line and the following pattern lines make up a section
+ of the actions file. 

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

- Actions are invoked by enclosing the action name in curly braces (e.g.
- {+some_action}), followed by a list of URLs (or patterns that match URLs) to
- which the action applies. There are three classes of actions: 
+ There are three classes of actions:

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

-

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

-   Boolean, i.e the action can only be <quote>on</quote> or
-   <quote>off</quote>. Examples: 
- </para>
+   Boolean, i.e the action can only be <quote>enabled</quote> or
+   <quote>disabled</quote>. Syntax:
+  </para>

   <para>
   <para>

-   <literal>
-    <msgtext> 
-     <literallayout>
-  <emphasis>{+name}</emphasis>        # enable this action
-  <emphasis>{-name}</emphasis>        # disable this action
-     </literallayout>
-    </msgtext> 
-   </literal>
+   <screen>
+  +<replaceable class="function">name</replaceable>        # enable action <replaceable class="parameter">name</replaceable>
+  -<replaceable class="function">name</replaceable>        # disable action <replaceable class="parameter">name</replaceable></screen>
+  </para>
+  <para>  
+   Example: <literal>+block</literal>

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

-   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:
+   Parameterized, where some value is required in order to enable this type of action.
+   Syntax:

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

-   <literal>
-    <msgtext> 
-     <literallayout>
-  <emphasis>{+name{param}}</emphasis>  # enable action and set parameter to <quote>param</quote>
-  <emphasis>{-name}</emphasis>         # disable action (<quote>parameter</quote>) can be omitted
-     </literallayout>
-    </msgtext> 
-   </literal>
+   <screen>
+  +<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>}  # enable action and set parameter to <replaceable class="parameter">param</replaceable>,
+               # overwriting parameter from previous match if necessary
+  -<replaceable class="function">name</replaceable>         # disable action. The parameter can be omitted</screen>
+  </para>
+  <para>
+   Note that if the URL matches multiple positive forms of a parameterized action,
+   the last match wins, i.e. the params from earlier matches are simply ignored.
+  </para>
+  <para>  
+   Example: <literal>+hide-user-agent{ Mozilla 1.0 }</literal>

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

-  <!-- oes, or someone, check this. Re-worded 04/20/02 HB. -->
-   Multi-value, e.g. <quote>{+/-add-header{Name: value}}</quote> or
-   <quote>{+/-send-wafer{name=value}}</quote>), where some value needs to be defined
-   in addition to simply enabling the action. Examples:
+   Multi-value. These look exactly like parameterized actions,
+   but they behave differently: If the action applies multiple times to the
+   same URL, but with different parameters, <emphasis>all</emphasis> the parameters
+   from <emphasis>all</emphasis> matches are remembered. This is used for actions
+   that can be executed for the same request repeatedly, like adding multiple
+   headers, or filtering through multiple filters. Syntax:

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

-   <literal>
-    <msgtext> 
-     <literallayout>
-  <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>
+   <screen>
+  +<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>}   # enable action and add <replaceable class="parameter">param</replaceable> to the list of parameters
+  -<replaceable class="function">name</replaceable>{<replaceable class="parameter">param</replaceable>}   # remove the parameter <replaceable class="parameter">param</replaceable> from the list of parameters
+                # If it was the last one left, disable the action.
+  <replaceable class="parameter">-name</replaceable>          # disable this action completely and remove all parameters from the list</screen>
+  </para>
+  <para>  
+   Examples: <literal>+add-header{X-Fun-Header: Some text}</literal> and
+   <literal>+filter{html-annoyances}</literal>

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


@@ -2994,12 +3053,12 @@ forward-socks4 and forward-socks4a</title>
  Actions files are processed in the order they are defined in
  <filename>config</filename> (the default installation has three actions
  files). It also quite possible for any given URL pattern to match more than
  Actions files are processed in the order they are defined in
  <filename>config</filename> (the default installation has three actions
  files). It also quite possible for any given URL pattern to match more than

- one action!
+ one pattern and thus more than one set of actions!

 </para>
 
 <!-- start actions listing -->
 <para>
 </para>
 
 <!-- start actions listing -->
 <para>

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

 </para>
 
 
 </para>
 
 


@@ -3025,10 +3084,10 @@ forward-socks4 and forward-socks4a</title>
  </varlistentry>
  
  <varlistentry>
  </varlistentry>
  
  <varlistentry>

-  <term>Typical uses:</term>
+  <term>Purpose and typical uses:</term>

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

-    Send a user defined HTTP header to the web server.
+    Send a user defined HTTP header to the web server. Can be used to confuse log analysis.

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


@@ -3038,6 +3097,8 @@ forward-socks4 and forward-socks4a</title>
   <listitem>
    <para>
     Any value is possible. Validity of the defined HTTP headers is not checked.
   <listitem>
    <para>
     Any value is possible. Validity of the defined HTTP headers is not checked.

+    It is recommended that you use the <quote><literal>X-</literal></quote> prefix
+    for custom headers.

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


@@ -3047,8 +3108,7 @@ forward-socks4 and forward-socks4a</title>
   <listitem>
     <literallayout>
      <emphasis>{+add-header{X-User-Tracking: sucks}}</emphasis>
   <listitem>
     <literallayout>
      <emphasis>{+add-header{X-User-Tracking: sucks}}</emphasis>

-     <emphasis>.example.com</emphasis>
-    </literallayout>
+     <emphasis>.example.com</emphasis></literallayout>

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


@@ -3081,12 +3141,14 @@ forward-socks4 and forward-socks4a</title>
  </varlistentry>
 
  <varlistentry>
  </varlistentry>
 
  <varlistentry>

-  <term>Typical uses:</term>
+  <term>Purpose and typical uses:</term>

   <listitem>
    <para>
   <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.    
+    Requests for URLs to which this action applies are blocked, i.e. the requests are not
+    forwarded to the remote server, but answered locally with a substitute page or image,
+    as determined by the <link linkend="handle-as-image">handle-as-image</link> and  
+    <link linkend="set-image-blocker">set-image-blocker</link> actions.
+    It is typically used to block ads or other obnoxious content.    

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


@@ -5831,6 +5893,10 @@ 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.101  2002/05/03 03:58:30  hal9
+ Move the user-manual config directive to top of section. Add note about
+ Privoxy needing read permissions for configs, and write for logs.
+

  Revision 1.100  2002/04/29 03:05:55  hal9
  Add clarification on differences of new actions files.
 
  Revision 1.100  2002/04/29 03:05:55  hal9
  Add clarification on differences of new actions files.