user-manual: Suggest to use the force-text-mode action when filtering binary content
[privoxy.git] / doc / source / user-manual.sgml
index 90702c4..ee41b2a 100644 (file)
 <!entity config SYSTEM "p-config.sgml">
 <!entity changelog SYSTEM "changelog.sgml">
 <!entity p-version "3.0.34">
-<!entity p-status "UNRELEASED">
+<!entity p-status "stable">
 <!entity % p-authors-formal "INCLUDE"> <!-- include additional text, etc  -->
-<!entity % p-not-stable "INCLUDE">
-<!entity % p-stable "IGNORE">
+<!entity % p-not-stable "IGNORE">
+<!entity % p-stable "INCLUDE">
 <!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">
@@ -35,7 +35,7 @@
 
  Purpose     :  user manual
 
- Copyright (C) 2001-2021 Privoxy Developers https://www.privoxy.org/
+ Copyright (C) 2001-2023 Privoxy Developers https://www.privoxy.org/
  See LICENSE.
 
  ========================================================================
@@ -54,7 +54,7 @@
  <subscript>
 <!-- Completely the wrong markup, but very little is allowed  -->
 <!-- in this part of an article. FIXME -->
- <link linkend="copyright">Copyright</link> &my-copy; 2001-2021 by
+ <link linkend="copyright">Copyright</link> &my-copy; 2001-2023 by
  <ulink url="https://www.privoxy.org/">Privoxy Developers</ulink>
  </subscript>
 </pubdate>
@@ -302,12 +302,16 @@ How to install the binary packages depends on your operating system:
 </sect3>
 
 <!--   ~~~~~       New section      ~~~~~     -->
-<sect3 id="installation-freebsd"><title>FreeBSD</title>
+<sect3 id="installation-freebsd"><title>FreeBSD and ElectroBSD</title>
 
 <para>
  Privoxy is part of FreeBSD's Ports Collection, you can build and install
  it with <literal>cd /usr/ports/www/privoxy; make install clean</literal>.
 </para>
+<para>
+ If your system is configured to install binary packages you can
+ try to install &my-app; with <literal>pkg install privoxy</literal>.
+</para>
 </sect3>
 
 </sect2>
@@ -409,8 +413,8 @@ MAKENSIS = /&lt;root-dir>/nsis/makensis.exe
 
       <para>
         Get the latest 8.x PCRE code from
-        <ulink url="https://ftp.pcre.org/pub/pcre/">PCRE
-                    https://ftp.pcre.org/pub/pcre/</ulink>
+        <ulink url="https://sourceforge.net/projects/pcre/files/pcre/">PCRE
+                    https://sourceforge.net/projects/pcre/files/pcre/</ulink>
         and build the static PCRE libraries with
 
         <screen>
@@ -437,9 +441,9 @@ export CPPFLAGS="-DPCRE_STATIC"
 
       <para>
         If you want to be able to have Privoxy do TLS Inspection, get the latest
-        2.16.x MBED-TLS library source code from
-        <ulink url="https://github.com/ARMmbed/mbedtls/tags">
-                    https://github.com/ARMmbed/mbedtls/tags</ulink>,
+        2.28.x MBED-TLS library source code from
+        <ulink url="https://github.com/Mbed-TLS/mbedtls/tags">
+                    https://github.com/Mbed-TLS/mbedtls/tags</ulink>,
         extract the tar file into <literal>&lt;root-dir&gt;</literal>
         and build the static libraries with
         <programlisting>
@@ -2536,12 +2540,6 @@ media.example.com/.*banners
 <!-- XXX: This section contains duplicates content from the
           client-specific-tag documentation. -->
 
-<warning>
-<para>
- This is an experimental feature. The syntax is likely to change in future versions.
-</para>
-</warning>
-
 <para>
  Client tag patterns are not set based on HTTP headers but based on
  the client's IP address. Users can enable them themselves, but the
@@ -4105,6 +4103,12 @@ problem-host.example.com</screen>
     linkend="external-filter-syntax">syntax</link></literal>
     may change in the future.
    </para>
+   <para>
+    If you want to apply external filters to images or other content
+    that isn't text-based, enable the
+    <literal><link linkend="force-text-mode">force-text-mode</link></literal>
+    action as well.
+   </para>
 
   </listitem>
  </varlistentry>
@@ -4465,6 +4469,10 @@ another.example.com/testing
     <anchor id="filter-no-ping">
    </para>
     <screen>+filter{no-ping}             # Removes non-standard ping attributes in &lt;a&gt; and &lt;area&gt; tags.</screen>
+   <para>
+    <anchor id="filter-bundeswehr.de">
+   </para>
+    <screen>+filter{bundeswehr.de}      # Hide the cookie and privacy info banner on bundeswehr.de.</screen>
    <para>
     <anchor id="filter-github">
    </para>
@@ -5450,9 +5458,6 @@ new action
     a pattern with path doesn't work as the path is only seen
     by &my-app; if the action is already enabled.
    </para>
-   <para>
-    This is an experimental feature.
-   </para>
   </listitem>
  </varlistentry>
 
@@ -7722,9 +7727,9 @@ pre-defined filters for your convenience:
   <term><emphasis>banners-by-link</emphasis></term>
   <listitem>
    <para>
-    This is an experimental filter that attempts to kill any banners if
-    their URLs seem to point to known or suspected click trackers. It is currently
-    not of much value and is not recommended for use by default.
+    This filter attempts to kill any banners if their URLs seem to point
+    to known or suspected click trackers. It is currently not of much value
+    and is not recommended for use by default.
    </para>
   </listitem>
  </varlistentry>
@@ -8206,7 +8211,7 @@ Requests</title>
 <para>
  The same is true for <application>Privoxy</application> binaries
  unless they are linked with a
- <ulink url="https://tls.mbed.org/">mbed TLS</ulink> version
+ <ulink url="https://www.trustedfirmware.org/projects/mbed-tls/">mbed TLS</ulink> version
  that is licensed under the Apache 2.0 license in which
  case you can redistribute and/or modify the <application>Privoxy</application>
  binaries under the terms of the <citetitle>GNU General Public License</citetitle>
@@ -8246,7 +8251,7 @@ Requests</title>
  When compiled with FEATURE_HTTPS_INSPECTION (optional),
  Privoxy depends on a TLS library. The supported libraries are
  <ulink url="https://www.openssl.org/">LibreSSL</ulink>,
- <ulink url="https://tls.mbed.org/">mbed TLS</ulink> and
+ <ulink url="https://github.com/Mbed-TLS/mbedtls/tags">mbed TLS 2.28.x</ulink> and
  <ulink url="https://www.openssl.org/">OpenSSL</ulink>.
 </para>
 <para>