X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=bd533593aa3379d07fe45e049d5a7a29474a6fcf;hb=6a3b20f8d70a7358f458ef4c007e656b53096cf7;hp=0892858fb696e0c325613ed71d59d800f42c6363;hpb=f1b952f2782de37718e135ff97a04c5c0185494d;p=privoxy.git
diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml
index 0892858f..bd533593 100644
--- a/doc/source/user-manual.sgml
+++ b/doc/source/user-manual.sgml
@@ -13,7 +13,7 @@
-
+
@@ -36,9 +36,9 @@
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 2.169 2013/02/26 15:10:49 fabiankeil Exp $
+ $Id: user-manual.sgml,v 2.185 2014/06/02 06:22:22 fabiankeil Exp $
- Copyright (C) 2001-2013 Privoxy Developers http://www.privoxy.org/
+ Copyright (C) 2001-2014 Privoxy Developers http://www.privoxy.org/
See LICENSE.
========================================================================
@@ -57,12 +57,12 @@
- Copyright &my-copy; 2001-2013 by
+ Copyright &my-copy; 2001-2014 by
Privoxy Developers
-$Id: user-manual.sgml,v 2.169 2013/02/26 15:10:49 fabiankeil Exp $
+$Id: user-manual.sgml,v 2.185 2014/06/02 06:22:22 fabiankeil Exp $
-The Domain Pattern
+The Host Pattern
- The matching of the domain part offers some flexible options: if the
- domain starts or ends with a dot, it becomes unanchored at that end.
+ The matching of the host part offers some flexible options: if the
+ host pattern starts or ends with a dot, it becomes unanchored at that end.
+ The host pattern is often referred to as domain pattern as it is usually
+ used to match domain names and not IP addresses.
For example:
@@ -2363,6 +2375,23 @@ for details.
+
+The Negative Tag Patterns
+
+
+ To match requests that do not have a certain tag, specify a negative tag pattern
+ by prefixing the tag pattern line with either NO-REQUEST-TAG:
+ or NO-RESPONSE-TAG: instead of TAG:.
+
+
+
+ Negative tag patterns created with NO-REQUEST-TAG: are checked
+ after all client headers are scanned, the ones created with NO-RESPONSE-TAG:
+ are checked after all server headers are scanned. In both cases all the created
+ tags are considered.
+
+
+
@@ -3572,6 +3601,92 @@ problem-host.example.com
+
+
+external-filter
+
+
+
+ Typical use:
+
+ Modify content using a programming language of your choice.
+
+
+
+
+ Effect:
+
+
+ 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 text/plain MIME type for all files
+ whose type they don't know.)
+
+
+
+
+
+ Type:
+
+
+ Parameterized.
+
+
+
+
+ Parameter:
+
+
+ The name of an external content filter, as defined in the
+ filter file.
+ External filters can be defined in one or more files as defined by the
+ filterfile
+ option in the config file.
+
+
+ When used in its negative form,
+ and without parameters, all filtering with external
+ filters is completely disabled.
+
+
+
+
+
+ Notes:
+
+
+ External filters are scripts or programs that can modify the content in
+ case common filters
+ aren't powerful enough.
+
+
+
+ Currently external filters are executed with &my-app;'s privileges.
+ Only use external filters you understand and trust.
+
+
+
+ This feature is experimental, the syntax
+ may change in the future.
+
+
+
+
+
+
+ Example usage:
+
+
+ +external-filter{fancy-filter}
+
+
+
+
+
+
fast-redirects
@@ -3834,7 +3949,7 @@ problem-host.example.com
- +filter{js-events} # Kill all JS event bindings and timers (Radically destructive! Only for extra nasty sites).
+ +filter{js-events} # Kill JavaScript event bindings and timers (Radically destructive! Only for extra nasty sites).
@@ -3846,15 +3961,15 @@ problem-host.example.com
- +filter{refresh-tags} # Kill automatic refresh tags (for dial-on-demand setups).
+ +filter{refresh-tags} # Kill automatic refresh tags if refresh time is larger than 9 seconds.
- +filter{unsolicited-popups} # Disable only unsolicited pop-up windows. Useful if your browser lacks this ability.
+ +filter{unsolicited-popups} # Disable only unsolicited pop-up windows.
- +filter{all-popups} # Kill all popups in JavaScript and HTML. Useful if your browser lacks this ability.
+ +filter{all-popups} # Kill all popups in JavaScript and HTML.
@@ -3884,6 +3999,10 @@ problem-host.example.com
+filter{frameset-borders} # Give frames a border and make them resizable.
+
+
+ +filter{iframes} # Removes all detected iframes. Should only be enabled for individual sites.
+ +filter{demoronizer} # Fix MS's non-standard use of standard charsets.
@@ -5274,7 +5393,7 @@ new action
example.com/stylesheet\.css
# Create a short, easy to remember nickname for a favorite site
-# (relies on the browser accept and forward invalid URLs to &my-app;)
+# (relies on the browser to accept and forward invalid URLs to &my-app;)
{ +redirect{http://www.privoxy.org/user-manual/actions-file.html} }
a
@@ -5292,6 +5411,13 @@ undeadly.org/cgi\?action=article&sid=\d*$
{+redirect{s@^http://[^/]*/results\.aspx\?q=([^&]*).*@http://search.yahoo.com/search?p=$1@}}
search.msn.com//results\.aspx\?q=
+# Redirect http://example.com/&bla=fasel&toChange=foo (and any other value but "bar")
+# to http://example.com/&bla=fasel&toChange=bar
+#
+# The URL pattern makes sure that the following request isn't redirected again.
+{+redirect{s@toChange=[^&]+@toChange=bar@}}
+example.com/.*toChange=(?!bar)
+
# Redirect remote requests for this manual
# to the local version delivered by Privoxy
{+redirect{s@^http://www@http://config@}}
@@ -6420,7 +6546,7 @@ stupid-server.example.com/
- &my-app; supports three different filter actions:
+ &my-app; supports three different pcrs-based filter actions:
filter to
rewrite the content that is send to the client,
client-header-filter
@@ -6440,6 +6566,13 @@ stupid-server.example.com/
applying actions through sections with tag-patterns.
+
+ Finally &my-app; supports the
+ external-filter action
+ to enable external filters
+ written in proper programming languages.
+
+
Multiple filter files can be defined through the
in a syntax that imitates Perl's
s/// operator. If you are familiar with Perl, you
will find this to be quite intuitive, and may want to look at the
- PCRS documentation for the subtle differences to Perl behaviour. Most
- notably, the non-standard option letter U is supported,
- which turns the default to ungreedy matching.
+ PCRS documentation for the subtle differences to Perl behaviour.
+
+
+
+ Most notably, the non-standard option letter U is supported,
+ which turns the default to ungreedy matching (add ? to
+ quantifiers to turn them greedy again).
+
+
+
+ The non-standard option letter D (dynamic) allows
+ to use the variables $host, $origin (the IP address the request came from),
+ $path and $url. They will be replaced with the value they refer to before
+ the filter is executed.
+
+
+
+ Note that '$' is a bad choice for a delimiter in a dynamic filter as you
+ might end up with unintended variables if you use a variable name
+ directly after the delimiter. Variables will be resolved without
+ escaping anything, therefore you also have to be careful not to chose
+ delimiters that appear in the replacement text. For example '<' should
+ be save, while '?' will sooner or later cause conflicts with $url.
+
+
+
+ The non-standard option letter T (trivial) prevents
+ parsing for backreferences in the substitute. Use it if you want to include
+ text like '$&' in your substitute without quoting.
@@ -7231,6 +7390,72 @@ pre-defined filters for your convenience:
+
+
+External filter syntax
+
+ External filters are scripts or programs that can modify the content in
+ case common filters
+ aren't powerful enough.
+
+
+ External filters can be written in any language the platform &my-app; runs
+ on supports.
+
+
+ They are controlled with the
+ external-filter action
+ and have to be defined in the filterfile
+ first.
+
+
+ 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).
+
+
+ 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.
+
+
+ &my-app; will temporary store the content to filter in the
+ temporary-directory.
+
+
+
+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
+
+
+
+
+
+ Currently external filters are executed with &my-app;'s privileges!
+ Only use external filters you understand and trust.
+
+
+
+ External filters are experimental and the syntax may change in the future.
+
+
+
@@ -7360,7 +7585,7 @@ Requests
-License
+License