Rebuild HTML docs for external filters
authorFabian Keil <fk@fabiankeil.de>
Mon, 2 Jun 2014 06:24:51 +0000 (06:24 +0000)
committerFabian Keil <fk@fabiankeil.de>
Mon, 2 Jun 2014 06:24:51 +0000 (06:24 +0000)
doc/webserver/developer-manual/index.html
doc/webserver/faq/index.html
doc/webserver/user-manual/actions-file.html
doc/webserver/user-manual/appendix.html
doc/webserver/user-manual/config.html
doc/webserver/user-manual/filter-file.html
doc/webserver/user-manual/index.html

index 10ead45..fee81f1 100644 (file)
@@ -24,8 +24,8 @@
       "http://www.privoxy.org/" target="_top">Privoxy
       Developers</a></sub><br></p>
 
-      <p class="PUBDATE">$Id: developer-manual.sgml,v 2.57 2013/03/01
-      17:44:24 fabiankeil Exp $<br></p>
+      <p class="PUBDATE">$Id: developer-manual.sgml,v 2.58 2014/05/26
+      10:48:39 fabiankeil Exp $<br></p>
 
       <div>
         <div class="ABSTRACT">
index 296bcf5..eb7102d 100644 (file)
@@ -22,7 +22,7 @@
       2001-2011 by <a href="http://www.privoxy.org/" target="_top">Privoxy
       Developers</a></sub><br></p>
 
-      <p class="PUBDATE">$Id: faq.sgml,v 2.100 2014/05/05 09:59:30 fabiankeil
+      <p class="PUBDATE">$Id: faq.sgml,v 2.101 2014/05/26 10:48:39 fabiankeil
       Exp $<br></p>
 
       <div>
index 221e7e2..993e9ca 100644 (file)
         in <tt class="FILENAME">default.action</tt> are:</p>
 
         <div class="TABLE">
-          <a name="AEN2863" id="AEN2863"></a>
+          <a name="AEN2891" id="AEN2891"></a>
 
           <p><b>Table 1. Default Configurations</b></p>
 
     actions</a>.</p>
 
     <div class="SECT2">
-      <h2 class="SECT2"><a name="AEN2962" id="AEN2962">8.1. Finding the Right
+      <h2 class="SECT2"><a name="AEN2990" id="AEN2990">8.1. Finding the Right
       Mix</a></h2>
 
       <p>Note that some <a href="actions-file.html#ACTIONS">actions</a>, like
     </div>
 
     <div class="SECT2">
-      <h2 class="SECT2"><a name="AEN2969" id="AEN2969">8.2. How to
+      <h2 class="SECT2"><a name="AEN2997" id="AEN2997">8.2. How to
       Edit</a></h2>
 
       <p>The easiest way to edit the actions files is with a browser by using
       </div>
 
       <div class="SECT3">
-        <h3 class="SECT3"><a name="AEN3163" id="AEN3163">8.4.2. The Path
+        <h3 class="SECT3"><a name="AEN3191" id="AEN3191">8.4.2. The Path
         Pattern</a></h3>
 
         <p><span class="APPLICATION">Privoxy</span> uses <span class=
@@ -1999,9 +1999,101 @@ problem-host.example.com
         </div>
       </div>
 
+      <div class="SECT3">
+        <h4 class="SECT3"><a name="EXTERNAL-FILTER" id=
+        "EXTERNAL-FILTER">8.5.14. external-filter</a></h4>
+
+        <div class="VARIABLELIST">
+          <dl>
+            <dt>Typical use:</dt>
+
+            <dd>
+              <p>Modify content using a programming language of your
+              choice.</p>
+            </dd>
+
+            <dt>Effect:</dt>
+
+            <dd>
+              <p>All instances of text-based type, most notably HTML and
+              JavaScript, to which this action applies, can be filtered
+              on-the-fly through the specified external filter. By default
+              plain text documents are exempted from filtering, because web
+              servers often use the <tt class="LITERAL">text/plain</tt> MIME
+              type for all files whose type they don't know.)</p>
+            </dd>
+
+            <dt>Type:</dt>
+
+            <dd>
+              <p>Parameterized.</p>
+            </dd>
+
+            <dt>Parameter:</dt>
+
+            <dd>
+              <p>The name of an external content filter, as defined in the
+              <a href="filter-file.html">filter file</a>. External filters
+              can be defined in one or more files as defined by the
+              <tt class="LITERAL"><a href=
+              "config.html#FILTERFILE">filterfile</a></tt> option in the
+              <a href="config.html">config file</a>.</p>
+
+              <p>When used in its negative form, and without parameters,
+              <span class="emphasis"><i class="EMPHASIS">all</i></span>
+              filtering with external filters is completely disabled.</p>
+            </dd>
+
+            <dt>Notes:</dt>
+
+            <dd>
+              <p>External filters are scripts or programs that can modify the
+              content in case common <tt class="LITERAL"><a href=
+              "actions-file.html#FILTER">filters</a></tt> aren't powerful
+              enough.</p>
+
+              <div class="WARNING">
+                <table class="WARNING" border="1" width="90%">
+                  <tr>
+                    <td align="center"><b>Warning</b></td>
+                  </tr>
+
+                  <tr>
+                    <td align="left">
+                      <p>Currently external filters are executed with
+                      <span class="APPLICATION">Privoxy</span>'s privileges.
+                      Only use external filters you understand and trust.</p>
+                    </td>
+                  </tr>
+                </table>
+              </div>
+
+              <p>This feature is experimental, the <tt class=
+              "LITERAL"><a href=
+              "filter-file.html#EXTERNAL-FILTER-SYNTAX">syntax</a></tt> may
+              change in the future.</p>
+            </dd>
+
+            <dt>Example usage:</dt>
+
+            <dd>
+              <table border="0" bgcolor="#E0E0E0" width="90%">
+                <tr>
+                  <td>
+                    <pre class="SCREEN">
++external-filter{fancy-filter}
+</pre>
+                  </td>
+                </tr>
+              </table>
+            </dd>
+          </dl>
+        </div>
+      </div>
+
       <div class="SECT3">
         <h4 class="SECT3"><a name="FAST-REDIRECTS" id=
-        "FAST-REDIRECTS">8.5.14. fast-redirects</a></h4>
+        "FAST-REDIRECTS">8.5.15. fast-redirects</a></h4>
 
         <div class="VARIABLELIST">
           <dl>
@@ -2123,7 +2215,7 @@ problem-host.example.com
       </div>
 
       <div class="SECT3">
-        <h4 class="SECT3"><a name="FILTER" id="FILTER">8.5.15.
+        <h4 class="SECT3"><a name="FILTER" id="FILTER">8.5.16.
         filter</a></h4>
 
         <div class="VARIABLELIST">
@@ -2597,7 +2689,7 @@ problem-host.example.com
 
       <div class="SECT3">
         <h4 class="SECT3"><a name="FORCE-TEXT-MODE" id=
-        "FORCE-TEXT-MODE">8.5.16. force-text-mode</a></h4>
+        "FORCE-TEXT-MODE">8.5.17. force-text-mode</a></h4>
 
         <div class="VARIABLELIST">
           <dl>
@@ -2678,7 +2770,7 @@ problem-host.example.com
 
       <div class="SECT3">
         <h4 class="SECT3"><a name="FORWARD-OVERRIDE" id=
-        "FORWARD-OVERRIDE">8.5.17. forward-override</a></h4>
+        "FORWARD-OVERRIDE">8.5.18. forward-override</a></h4>
 
         <div class="VARIABLELIST">
           <dl>
@@ -2811,7 +2903,7 @@ TAG:^User-Agent: fetch libfetch/2\.0$
 
       <div class="SECT3">
         <h4 class="SECT3"><a name="HANDLE-AS-EMPTY-DOCUMENT" id=
-        "HANDLE-AS-EMPTY-DOCUMENT">8.5.18. handle-as-empty-document</a></h4>
+        "HANDLE-AS-EMPTY-DOCUMENT">8.5.19. handle-as-empty-document</a></h4>
 
         <div class="VARIABLELIST">
           <dl>
@@ -2889,7 +2981,7 @@ example.org/.*\.js$
 
       <div class="SECT3">
         <h4 class="SECT3"><a name="HANDLE-AS-IMAGE" id=
-        "HANDLE-AS-IMAGE">8.5.19. handle-as-image</a></h4>
+        "HANDLE-AS-IMAGE">8.5.20. handle-as-image</a></h4>
 
         <div class="VARIABLELIST">
           <dl>
@@ -2978,7 +3070,7 @@ nasty-banner-server.example.com/junk.cgi\?output=trash
 
       <div class="SECT3">
         <h4 class="SECT3"><a name="HIDE-ACCEPT-LANGUAGE" id=
-        "HIDE-ACCEPT-LANGUAGE">8.5.20. hide-accept-language</a></h4>
+        "HIDE-ACCEPT-LANGUAGE">8.5.21. hide-accept-language</a></h4>
 
         <div class="VARIABLELIST">
           <dl>
@@ -3058,7 +3150,7 @@ nasty-banner-server.example.com/junk.cgi\?output=trash
 
       <div class="SECT3">
         <h4 class="SECT3"><a name="HIDE-CONTENT-DISPOSITION" id=
-        "HIDE-CONTENT-DISPOSITION">8.5.21. hide-content-disposition</a></h4>
+        "HIDE-CONTENT-DISPOSITION">8.5.22. hide-content-disposition</a></h4>
 
         <div class="VARIABLELIST">
           <dl>
@@ -3144,7 +3236,7 @@ nasty-banner-server.example.com/junk.cgi\?output=trash
 
       <div class="SECT3">
         <h4 class="SECT3"><a name="HIDE-IF-MODIFIED-SINCE" id=
-        "HIDE-IF-MODIFIED-SINCE">8.5.22. hide-if-modified-since</a></h4>
+        "HIDE-IF-MODIFIED-SINCE">8.5.23. hide-if-modified-since</a></h4>
 
         <div class="VARIABLELIST">
           <dl>
@@ -3231,7 +3323,7 @@ nasty-banner-server.example.com/junk.cgi\?output=trash
 
       <div class="SECT3">
         <h4 class="SECT3"><a name="HIDE-FROM-HEADER" id=
-        "HIDE-FROM-HEADER">8.5.23. hide-from-header</a></h4>
+        "HIDE-FROM-HEADER">8.5.24. hide-from-header</a></h4>
 
         <div class="VARIABLELIST">
           <dl>
@@ -3306,7 +3398,7 @@ nasty-banner-server.example.com/junk.cgi\?output=trash
       </div>
 
       <div class="SECT3">
-        <h4 class="SECT3"><a name="HIDE-REFERRER" id="HIDE-REFERRER">8.5.24.
+        <h4 class="SECT3"><a name="HIDE-REFERRER" id="HIDE-REFERRER">8.5.25.
         hide-referrer</a></h4><a name="HIDE-REFERER" id="HIDE-REFERER"></a>
 
         <div class="VARIABLELIST">
@@ -3426,7 +3518,7 @@ nasty-banner-server.example.com/junk.cgi\?output=trash
 
       <div class="SECT3">
         <h4 class="SECT3"><a name="HIDE-USER-AGENT" id=
-        "HIDE-USER-AGENT">8.5.25. hide-user-agent</a></h4>
+        "HIDE-USER-AGENT">8.5.26. hide-user-agent</a></h4>
 
         <div class="VARIABLELIST">
           <dl>
@@ -3515,7 +3607,7 @@ nasty-banner-server.example.com/junk.cgi\?output=trash
       </div>
 
       <div class="SECT3">
-        <h4 class="SECT3"><a name="LIMIT-CONNECT" id="LIMIT-CONNECT">8.5.26.
+        <h4 class="SECT3"><a name="LIMIT-CONNECT" id="LIMIT-CONNECT">8.5.27.
         limit-connect</a></h4>
 
         <div class="VARIABLELIST">
@@ -3596,7 +3688,7 @@ nasty-banner-server.example.com/junk.cgi\?output=trash
 
       <div class="SECT3">
         <h4 class="SECT3"><a name="LIMIT-COOKIE-LIFETIME" id=
-        "LIMIT-COOKIE-LIFETIME">8.5.27. limit-cookie-lifetime</a></h4>
+        "LIMIT-COOKIE-LIFETIME">8.5.28. limit-cookie-lifetime</a></h4>
 
         <div class="VARIABLELIST">
           <dl>
@@ -3678,7 +3770,7 @@ nasty-banner-server.example.com/junk.cgi\?output=trash
 
       <div class="SECT3">
         <h4 class="SECT3"><a name="PREVENT-COMPRESSION" id=
-        "PREVENT-COMPRESSION">8.5.28. prevent-compression</a></h4>
+        "PREVENT-COMPRESSION">8.5.29. prevent-compression</a></h4>
 
         <div class="VARIABLELIST">
           <dl>
@@ -3782,7 +3874,7 @@ nasty-banner-server.example.com/junk.cgi\?output=trash
 
       <div class="SECT3">
         <h4 class="SECT3"><a name="OVERWRITE-LAST-MODIFIED" id=
-        "OVERWRITE-LAST-MODIFIED">8.5.29. overwrite-last-modified</a></h4>
+        "OVERWRITE-LAST-MODIFIED">8.5.30. overwrite-last-modified</a></h4>
 
         <div class="VARIABLELIST">
           <dl>
@@ -3878,7 +3970,7 @@ nasty-banner-server.example.com/junk.cgi\?output=trash
       </div>
 
       <div class="SECT3">
-        <h4 class="SECT3"><a name="REDIRECT" id="REDIRECT">8.5.30.
+        <h4 class="SECT3"><a name="REDIRECT" id="REDIRECT">8.5.31.
         redirect</a></h4>
 
         <div class="VARIABLELIST">
@@ -3982,7 +4074,7 @@ www.privoxy.org/user-manual/
 
       <div class="SECT3">
         <h4 class="SECT3"><a name="SERVER-HEADER-FILTER" id=
-        "SERVER-HEADER-FILTER">8.5.31. server-header-filter</a></h4>
+        "SERVER-HEADER-FILTER">8.5.32. server-header-filter</a></h4>
 
         <div class="VARIABLELIST">
           <dl>
@@ -4054,7 +4146,7 @@ example.org/instance-that-is-delivered-as-xml-but-is-not
 
       <div class="SECT3">
         <h4 class="SECT3"><a name="SERVER-HEADER-TAGGER" id=
-        "SERVER-HEADER-TAGGER">8.5.32. server-header-tagger</a></h4>
+        "SERVER-HEADER-TAGGER">8.5.33. server-header-tagger</a></h4>
 
         <div class="VARIABLELIST">
           <dl>
@@ -4127,7 +4219,7 @@ example.org/instance-that-is-delivered-as-xml-but-is-not
 
       <div class="SECT3">
         <h4 class="SECT3"><a name="SESSION-COOKIES-ONLY" id=
-        "SESSION-COOKIES-ONLY">8.5.33. session-cookies-only</a></h4>
+        "SESSION-COOKIES-ONLY">8.5.34. session-cookies-only</a></h4>
 
         <div class="VARIABLELIST">
           <dl>
@@ -4225,7 +4317,7 @@ example.org/instance-that-is-delivered-as-xml-but-is-not
 
       <div class="SECT3">
         <h4 class="SECT3"><a name="SET-IMAGE-BLOCKER" id=
-        "SET-IMAGE-BLOCKER">8.5.34. set-image-blocker</a></h4>
+        "SET-IMAGE-BLOCKER">8.5.35. set-image-blocker</a></h4>
 
         <div class="VARIABLELIST">
           <dl>
@@ -4364,7 +4456,7 @@ example.org/instance-that-is-delivered-as-xml-but-is-not
       </div>
 
       <div class="SECT3">
-        <h3 class="SECT3"><a name="AEN4847" id="AEN4847">8.5.35.
+        <h3 class="SECT3"><a name="AEN4918" id="AEN4918">8.5.36.
         Summary</a></h3>
 
         <p>Note that many of these actions have the potential to cause a page
@@ -4523,7 +4615,7 @@ example.org/instance-that-is-delivered-as-xml-but-is-not
       together:</p>
 
       <div class="SECT3">
-        <h3 class="SECT3"><a name="AEN4911" id="AEN4911">8.7.1.
+        <h3 class="SECT3"><a name="AEN4982" id="AEN4982">8.7.1.
         match-all.action</a></h3>
 
         <p>Remember <span class="emphasis"><i class="EMPHASIS">all actions
@@ -4572,7 +4664,7 @@ example.org/instance-that-is-delivered-as-xml-but-is-not
       </div>
 
       <div class="SECT3">
-        <h3 class="SECT3"><a name="AEN4933" id="AEN4933">8.7.2.
+        <h3 class="SECT3"><a name="AEN5004" id="AEN5004">8.7.2.
         default.action</a></h3>
 
         <p>If you aren't a developer, there's no need for you to edit the
@@ -4915,7 +5007,7 @@ wiki.
       </div>
 
       <div class="SECT3">
-        <h3 class="SECT3"><a name="AEN5046" id="AEN5046">8.7.3.
+        <h3 class="SECT3"><a name="AEN5117" id="AEN5117">8.7.3.
         user.action</a></h3>
 
         <p>So far we are painting with a broad brush by setting general
index 54fb476..34cf2ec 100644 (file)
     </div>
 
     <div class="SECT2">
-      <h2 class="SECT2"><a name="AEN5929" id="AEN5929">14.2. Privoxy's
+      <h2 class="SECT2"><a name="AEN6030" id="AEN6030">14.2. Privoxy's
       Internal Pages</a></h2>
 
       <p>Since <span class="APPLICATION">Privoxy</span> proxies each
 
       <ul>
         <li>
-          <p>Privoxy main page:</p><a name="AEN5943" id="AEN5943"></a>
+          <p>Privoxy main page:</p><a name="AEN6044" id="AEN6044"></a>
 
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/" target=
 
         <li>
           <p>Show information about the current configuration, including
-          viewing and editing of actions files:</p><a name="AEN5951" id=
-          "AEN5951"></a>
+          viewing and editing of actions files:</p><a name="AEN6052" id=
+          "AEN6052"></a>
 
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/show-status" target=
         </li>
 
         <li>
-          <p>Show the source code version numbers:</p><a name="AEN5956" id=
-          "AEN5956"></a>
+          <p>Show the source code version numbers:</p><a name="AEN6057" id=
+          "AEN6057"></a>
 
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/show-version" target=
         </li>
 
         <li>
-          <p>Show the browser's request headers:</p><a name="AEN5961" id=
-          "AEN5961"></a>
+          <p>Show the browser's request headers:</p><a name="AEN6062" id=
+          "AEN6062"></a>
 
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/show-request" target=
         </li>
 
         <li>
-          <p>Show which actions apply to a URL and why:</p><a name="AEN5966"
-          id="AEN5966"></a>
+          <p>Show which actions apply to a URL and why:</p><a name="AEN6067"
+          id="AEN6067"></a>
 
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/show-url-info" target=
           <span class="QUOTE">"off"</span>, <span class=
           "QUOTE">"Privoxy"</span> continues to run, but only as a
           pass-through proxy, with no actions taking place:</p><a name=
-          "AEN5974" id="AEN5974"></a>
+          "AEN6075" id="AEN6075"></a>
 
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/toggle" target=
             "_top">http://config.privoxy.org/toggle</a></p>
           </blockquote>
 
-          <p>Short cuts. Turn off, then on:</p><a name="AEN5978" id=
-          "AEN5978"></a>
+          <p>Short cuts. Turn off, then on:</p><a name="AEN6079" id=
+          "AEN6079"></a>
 
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/toggle?set=disable" target=
             "_top">http://config.privoxy.org/toggle?set=disable</a></p>
-          </blockquote><a name="AEN5981" id="AEN5981"></a>
+          </blockquote><a name="AEN6082" id="AEN6082"></a>
 
           <blockquote class="BLOCKQUOTE">
             <p><a href="http://config.privoxy.org/toggle?set=enable" target=
index 0ac3f66..f7a1e77 100644 (file)
       </div>
 
       <div class="SECT3">
-        <h4 class="SECT3"><a name="LOGDIR" id="LOGDIR">7.2.3. logdir</a></h4>
+        <h4 class="SECT3"><a name="TEMPORARY-DIRECTORY" id=
+        "TEMPORARY-DIRECTORY">7.2.3. temporary-directory</a></h4>
+
+        <div class="VARIABLELIST">
+          <dl>
+            <dt>Specifies:</dt>
+
+            <dd>
+              <p>A directory where Privoxy can create temporary files.</p>
+            </dd>
+
+            <dt>Type of value:</dt>
+
+            <dd>
+              <p>Path name</p>
+            </dd>
+
+            <dt>Default value:</dt>
+
+            <dd>
+              <p>unset</p>
+            </dd>
+
+            <dt>Effect if unset:</dt>
+
+            <dd>
+              <p>No temporary files are created, external filters don't
+              work.</p>
+            </dd>
+
+            <dt>Notes:</dt>
+
+            <dd>
+              <p>To execute <tt class="LITERAL"><a href=
+              "actions-file.html#EXTERNAL-FILTER" target="_top">external
+              filters</a></tt>, <span class="APPLICATION">Privoxy</span> has
+              to create temporary files. This directive specifies the
+              directory the temporary files should be written to.</p>
+
+              <p>It should be a directory only <span class=
+              "APPLICATION">Privoxy</span> (and trusted users) can
+              access.</p>
+            </dd>
+          </dl>
+        </div>
+      </div>
+
+      <div class="SECT3">
+        <h4 class="SECT3"><a name="LOGDIR" id="LOGDIR">7.2.4. logdir</a></h4>
 
         <div class="VARIABLELIST">
           <dl>
       </div>
 
       <div class="SECT3">
-        <h4 class="SECT3"><a name="ACTIONSFILE" id="ACTIONSFILE">7.2.4.
+        <h4 class="SECT3"><a name="ACTIONSFILE" id="ACTIONSFILE">7.2.5.
         actionsfile</a></h4><a name="DEFAULT.ACTION" id=
         "DEFAULT.ACTION"></a><a name="STANDARD.ACTION" id=
         "STANDARD.ACTION"></a><a name="USER.ACTION" id="USER.ACTION"></a>
       </div>
 
       <div class="SECT3">
-        <h4 class="SECT3"><a name="FILTERFILE" id="FILTERFILE">7.2.5.
+        <h4 class="SECT3"><a name="FILTERFILE" id="FILTERFILE">7.2.6.
         filterfile</a></h4><a name="DEFAULT.FILTER" id="DEFAULT.FILTER"></a>
 
         <div class="VARIABLELIST">
       </div>
 
       <div class="SECT3">
-        <h4 class="SECT3"><a name="LOGFILE" id="LOGFILE">7.2.6.
+        <h4 class="SECT3"><a name="LOGFILE" id="LOGFILE">7.2.7.
         logfile</a></h4>
 
         <div class="VARIABLELIST">
       </div>
 
       <div class="SECT3">
-        <h4 class="SECT3"><a name="TRUSTFILE" id="TRUSTFILE">7.2.7.
+        <h4 class="SECT3"><a name="TRUSTFILE" id="TRUSTFILE">7.2.8.
         trustfile</a></h4>
 
         <div class="VARIABLELIST">
index 49284e0..09acb90 100644 (file)
@@ -45,7 +45,7 @@
     an <span class="QUOTE">"action"</span>.</p>
 
     <p><span class="APPLICATION">Privoxy</span> supports three different
-    filter actions: <tt class="LITERAL"><a href=
+    pcrs-based filter actions: <tt class="LITERAL"><a href=
     "actions-file.html#FILTER">filter</a></tt> to rewrite the content that is
     send to the client, <tt class="LITERAL"><a href=
     "actions-file.html#CLIENT-HEADER-FILTER">client-header-filter</a></tt> to
     used to change the applying actions through sections with <a href=
     "actions-file.html#TAG-PATTERN">tag-patterns</a>.</p>
 
+    <p>Finally <span class="APPLICATION">Privoxy</span> supports the
+    <tt class="LITERAL"><a href=
+    "actions-file.html#EXTERNAL-FILTER">external-filter</a></tt> action to
+    enable <tt class="LITERAL"><a href=
+    "filter-file.html#EXTERNAL-FILTER-SYNTAX">external filters</a></tt>
+    written in proper programming languages.</p>
+
     <p>Multiple filter files can be defined through the <tt class=
     "LITERAL"><a href="config.html#FILTERFILE">filterfile</a></tt> config
     directive. The filters as supplied by the developers are located in
@@ -170,7 +177,7 @@ FILTER: foo Replace all "foo" with "bar"
     started.</p>
 
     <div class="SECT2">
-      <h2 class="SECT2"><a name="AEN5208" id="AEN5208">9.1. Filter File
+      <h2 class="SECT2"><a name="AEN5285" id="AEN5285">9.1. Filter File
       Tutorial</a></h2>
 
       <p>Now, let's complete our <span class="QUOTE">"foo"</span> content
@@ -844,6 +851,81 @@ s* industry[ -]leading \
         </dl>
       </div>
     </div>
+
+    <div class="SECT2">
+      <h2 class="SECT2"><a name="EXTERNAL-FILTER-SYNTAX" id=
+      "EXTERNAL-FILTER-SYNTAX">9.3. External filter syntax</a></h2>
+
+      <p>External filters are scripts or programs that can modify the content
+      in case common <tt class="LITERAL"><a href=
+      "actions-file.html#FILTER">filters</a></tt> aren't powerful enough.</p>
+
+      <p>External filters can be written in any language the platform
+      <span class="APPLICATION">Privoxy</span> runs on supports.</p>
+
+      <p>They are controlled with the <tt class="LITERAL"><a href=
+      "actions-file.html#EXTERNAL-FILTER">external-filter</a></tt> action and
+      have to be defined in the <tt class="LITERAL"><a href=
+      "config.html#FILTERFILE">filterfile</a></tt> first.</p>
+
+      <p>The header looks like any other filter, but instead of pcrs jobs,
+      external filters contain a single job which can be a program or a shell
+      script (which may call other scripts or programs).</p>
+
+      <p>External filters read the content from STDIN and write the rewritten
+      content to STDOUT. The environment variables PRIVOXY_URL, PRIVOXY_PATH,
+      PRIVOXY_HOST, PRIVOXY_ORIGIN can be used to get some details about the
+      client request.</p>
+
+      <p><span class="APPLICATION">Privoxy</span> will temporary store the
+      content to filter in the <tt class="LITERAL"><a href=
+      "config.html#TEMPORARY-DIRECTORY">temporary-directory</a></tt>.</p>
+
+      <table border="0" bgcolor="#E0E0E0" width="100%">
+        <tr>
+          <td>
+            <pre class="SCREEN">
+EXTERNAL-FILTER: cat Pointless example filter that doesn't actually modify the content
+/bin/cat
+
+# Incorrect reimplementation of the filter above in POSIX shell.
+#
+# Note that it's a single job that spans multiple lines, the line
+# breaks are not passed to the shell, thus the semicolons are required.
+#
+# If the script isn't trivial, it is recommended to put it into an external file.
+#
+# In general, writing external filters entirely in POSIX shell is not
+# considered a good idea.
+EXTERNAL-FILTER: cat2 Pointless example filter that despite its name may actually modify the content
+while read line; \
+do \
+  echo "$line"; \
+done
+</pre>
+          </td>
+        </tr>
+      </table>
+
+      <div class="WARNING">
+        <table class="WARNING" border="1" width="100%">
+          <tr>
+            <td align="center"><b>Warning</b></td>
+          </tr>
+
+          <tr>
+            <td align="left">
+              <p>Currently external filters are executed with <span class=
+              "APPLICATION">Privoxy</span>'s privileges! Only use external
+              filters you understand and trust.</p>
+            </td>
+          </tr>
+        </table>
+      </div>
+
+      <p>External filters are experimental and the syntax may change in the
+      future.</p>
+    </div>
   </div>
 
   <div class="NAVFOOTER">
index 3746844..c1c1df7 100644 (file)
       Manual</a></h1>
 
       <p class="PUBDATE"><sub><a href="copyright.html">Copyright</a> &copy;
-      2001-2013 by <a href="http://www.privoxy.org/" target="_top">Privoxy
+      2001-2014 by <a href="http://www.privoxy.org/" target="_top">Privoxy
       Developers</a></sub><br></p>
 
-      <p class="PUBDATE">$Id: user-manual.sgml,v 2.182 2014/05/05 10:08:43
+      <p class="PUBDATE">$Id: user-manual.sgml,v 2.183 2014/05/26 10:48:39
       fabiankeil Exp $<br></p>
 
       <div>
 
                 <dt>7.2.2. <a href="config.html#TEMPLDIR">templdir</a></dt>
 
-                <dt>7.2.3. <a href="config.html#LOGDIR">logdir</a></dt>
+                <dt>7.2.3. <a href=
+                "config.html#TEMPORARY-DIRECTORY">temporary-directory</a></dt>
 
-                <dt>7.2.4. <a href=
-                "config.html#ACTIONSFILE">actionsfile</a></dt>
+                <dt>7.2.4. <a href="config.html#LOGDIR">logdir</a></dt>
 
                 <dt>7.2.5. <a href=
+                "config.html#ACTIONSFILE">actionsfile</a></dt>
+
+                <dt>7.2.6. <a href=
                 "config.html#FILTERFILE">filterfile</a></dt>
 
-                <dt>7.2.6. <a href="config.html#LOGFILE">logfile</a></dt>
+                <dt>7.2.7. <a href="config.html#LOGFILE">logfile</a></dt>
 
-                <dt>7.2.7. <a href="config.html#TRUSTFILE">trustfile</a></dt>
+                <dt>7.2.8. <a href="config.html#TRUSTFILE">trustfile</a></dt>
               </dl>
             </dd>
 
 
         <dd>
           <dl>
-            <dt>8.1. <a href="actions-file.html#AEN2962">Finding the Right
+            <dt>8.1. <a href="actions-file.html#AEN2990">Finding the Right
             Mix</a></dt>
 
-            <dt>8.2. <a href="actions-file.html#AEN2969">How to Edit</a></dt>
+            <dt>8.2. <a href="actions-file.html#AEN2997">How to Edit</a></dt>
 
             <dt>8.3. <a href="actions-file.html#ACTIONS-APPLY">How Actions
             are Applied to Requests</a></dt>
                 <dt>8.4.1. <a href="actions-file.html#HOST-PATTERN">The Host
                 Pattern</a></dt>
 
-                <dt>8.4.2. <a href="actions-file.html#AEN3163">The Path
+                <dt>8.4.2. <a href="actions-file.html#AEN3191">The Path
                 Pattern</a></dt>
 
                 <dt>8.4.3. <a href="actions-file.html#TAG-PATTERN">The Tag
                 "actions-file.html#DOWNGRADE-HTTP-VERSION">downgrade-http-version</a></dt>
 
                 <dt>8.5.14. <a href=
-                "actions-file.html#FAST-REDIRECTS">fast-redirects</a></dt>
+                "actions-file.html#EXTERNAL-FILTER">external-filter</a></dt>
 
                 <dt>8.5.15. <a href=
-                "actions-file.html#FILTER">filter</a></dt>
+                "actions-file.html#FAST-REDIRECTS">fast-redirects</a></dt>
 
                 <dt>8.5.16. <a href=
-                "actions-file.html#FORCE-TEXT-MODE">force-text-mode</a></dt>
+                "actions-file.html#FILTER">filter</a></dt>
 
                 <dt>8.5.17. <a href=
-                "actions-file.html#FORWARD-OVERRIDE">forward-override</a></dt>
+                "actions-file.html#FORCE-TEXT-MODE">force-text-mode</a></dt>
 
                 <dt>8.5.18. <a href=
-                "actions-file.html#HANDLE-AS-EMPTY-DOCUMENT">handle-as-empty-document</a></dt>
+                "actions-file.html#FORWARD-OVERRIDE">forward-override</a></dt>
 
                 <dt>8.5.19. <a href=
-                "actions-file.html#HANDLE-AS-IMAGE">handle-as-image</a></dt>
+                "actions-file.html#HANDLE-AS-EMPTY-DOCUMENT">handle-as-empty-document</a></dt>
 
                 <dt>8.5.20. <a href=
-                "actions-file.html#HIDE-ACCEPT-LANGUAGE">hide-accept-language</a></dt>
+                "actions-file.html#HANDLE-AS-IMAGE">handle-as-image</a></dt>
 
                 <dt>8.5.21. <a href=
-                "actions-file.html#HIDE-CONTENT-DISPOSITION">hide-content-disposition</a></dt>
+                "actions-file.html#HIDE-ACCEPT-LANGUAGE">hide-accept-language</a></dt>
 
                 <dt>8.5.22. <a href=
-                "actions-file.html#HIDE-IF-MODIFIED-SINCE">hide-if-modified-since</a></dt>
+                "actions-file.html#HIDE-CONTENT-DISPOSITION">hide-content-disposition</a></dt>
 
                 <dt>8.5.23. <a href=
-                "actions-file.html#HIDE-FROM-HEADER">hide-from-header</a></dt>
+                "actions-file.html#HIDE-IF-MODIFIED-SINCE">hide-if-modified-since</a></dt>
 
                 <dt>8.5.24. <a href=
-                "actions-file.html#HIDE-REFERRER">hide-referrer</a></dt>
+                "actions-file.html#HIDE-FROM-HEADER">hide-from-header</a></dt>
 
                 <dt>8.5.25. <a href=
-                "actions-file.html#HIDE-USER-AGENT">hide-user-agent</a></dt>
+                "actions-file.html#HIDE-REFERRER">hide-referrer</a></dt>
 
                 <dt>8.5.26. <a href=
-                "actions-file.html#LIMIT-CONNECT">limit-connect</a></dt>
+                "actions-file.html#HIDE-USER-AGENT">hide-user-agent</a></dt>
 
                 <dt>8.5.27. <a href=
-                "actions-file.html#LIMIT-COOKIE-LIFETIME">limit-cookie-lifetime</a></dt>
+                "actions-file.html#LIMIT-CONNECT">limit-connect</a></dt>
 
                 <dt>8.5.28. <a href=
-                "actions-file.html#PREVENT-COMPRESSION">prevent-compression</a></dt>
+                "actions-file.html#LIMIT-COOKIE-LIFETIME">limit-cookie-lifetime</a></dt>
 
                 <dt>8.5.29. <a href=
-                "actions-file.html#OVERWRITE-LAST-MODIFIED">overwrite-last-modified</a></dt>
+                "actions-file.html#PREVENT-COMPRESSION">prevent-compression</a></dt>
 
                 <dt>8.5.30. <a href=
-                "actions-file.html#REDIRECT">redirect</a></dt>
+                "actions-file.html#OVERWRITE-LAST-MODIFIED">overwrite-last-modified</a></dt>
 
                 <dt>8.5.31. <a href=
-                "actions-file.html#SERVER-HEADER-FILTER">server-header-filter</a></dt>
+                "actions-file.html#REDIRECT">redirect</a></dt>
 
                 <dt>8.5.32. <a href=
-                "actions-file.html#SERVER-HEADER-TAGGER">server-header-tagger</a></dt>
+                "actions-file.html#SERVER-HEADER-FILTER">server-header-filter</a></dt>
 
                 <dt>8.5.33. <a href=
-                "actions-file.html#SESSION-COOKIES-ONLY">session-cookies-only</a></dt>
+                "actions-file.html#SERVER-HEADER-TAGGER">server-header-tagger</a></dt>
 
                 <dt>8.5.34. <a href=
-                "actions-file.html#SET-IMAGE-BLOCKER">set-image-blocker</a></dt>
+                "actions-file.html#SESSION-COOKIES-ONLY">session-cookies-only</a></dt>
 
                 <dt>8.5.35. <a href=
-                "actions-file.html#AEN4847">Summary</a></dt>
+                "actions-file.html#SET-IMAGE-BLOCKER">set-image-blocker</a></dt>
+
+                <dt>8.5.36. <a href=
+                "actions-file.html#AEN4918">Summary</a></dt>
               </dl>
             </dd>
 
             <dd>
               <dl>
                 <dt>8.7.1. <a href=
-                "actions-file.html#AEN4911">match-all.action</a></dt>
+                "actions-file.html#AEN4982">match-all.action</a></dt>
 
                 <dt>8.7.2. <a href=
-                "actions-file.html#AEN4933">default.action</a></dt>
+                "actions-file.html#AEN5004">default.action</a></dt>
 
                 <dt>8.7.3. <a href=
-                "actions-file.html#AEN5046">user.action</a></dt>
+                "actions-file.html#AEN5117">user.action</a></dt>
               </dl>
             </dd>
           </dl>
 
         <dd>
           <dl>
-            <dt>9.1. <a href="filter-file.html#AEN5208">Filter File
+            <dt>9.1. <a href="filter-file.html#AEN5285">Filter File
             Tutorial</a></dt>
 
             <dt>9.2. <a href="filter-file.html#PREDEFINED-FILTERS">The
             Pre-defined Filters</a></dt>
+
+            <dt>9.3. <a href=
+            "filter-file.html#EXTERNAL-FILTER-SYNTAX">External filter
+            syntax</a></dt>
           </dl>
         </dd>
 
             <dt>14.1. <a href="appendix.html#REGEX">Regular
             Expressions</a></dt>
 
-            <dt>14.2. <a href="appendix.html#AEN5929">Privoxy's Internal
+            <dt>14.2. <a href="appendix.html#AEN6030">Privoxy's Internal
             Pages</a></dt>
 
             <dd>