From fe7be244869c9dd319ed2bf2a4f90ad498c96d34 Mon Sep 17 00:00:00 2001 From: Fabian Keil Date: Mon, 2 Jun 2014 06:24:51 +0000 Subject: [PATCH] Rebuild HTML docs for external filters --- doc/webserver/developer-manual/index.html | 4 +- doc/webserver/faq/index.html | 2 +- doc/webserver/user-manual/actions-file.html | 150 ++++++++++++++++---- doc/webserver/user-manual/appendix.html | 28 ++-- doc/webserver/user-manual/config.html | 58 +++++++- doc/webserver/user-manual/filter-file.html | 86 ++++++++++- doc/webserver/user-manual/index.html | 84 ++++++----- 7 files changed, 322 insertions(+), 90 deletions(-) diff --git a/doc/webserver/developer-manual/index.html b/doc/webserver/developer-manual/index.html index 10ead450..fee81f11 100644 --- a/doc/webserver/developer-manual/index.html +++ b/doc/webserver/developer-manual/index.html @@ -24,8 +24,8 @@ "http://www.privoxy.org/" target="_top">Privoxy Developers

-

$Id: developer-manual.sgml,v 2.57 2013/03/01 - 17:44:24 fabiankeil Exp $

+

$Id: developer-manual.sgml,v 2.58 2014/05/26 + 10:48:39 fabiankeil Exp $

diff --git a/doc/webserver/faq/index.html b/doc/webserver/faq/index.html index 296bcf55..eb7102db 100644 --- a/doc/webserver/faq/index.html +++ b/doc/webserver/faq/index.html @@ -22,7 +22,7 @@ 2001-2011 by Privoxy Developers

-

$Id: faq.sgml,v 2.100 2014/05/05 09:59:30 fabiankeil +

$Id: faq.sgml,v 2.101 2014/05/26 10:48:39 fabiankeil Exp $

diff --git a/doc/webserver/user-manual/actions-file.html b/doc/webserver/user-manual/actions-file.html index 221e7e2a..993e9ca5 100644 --- a/doc/webserver/user-manual/actions-file.html +++ b/doc/webserver/user-manual/actions-file.html @@ -117,7 +117,7 @@ in default.action are:

- +

Table 1. Default Configurations

@@ -314,7 +314,7 @@ actions.

-

8.1. Finding the Right +

8.1. Finding the Right Mix

Note that some actions, like @@ -339,7 +339,7 @@

-

8.2. How to +

8.2. How to Edit

The easiest way to edit the actions files is with a browser by using @@ -644,7 +644,7 @@

-

8.4.2. The Path +

8.4.2. The Path Pattern

Privoxy uses

+
+

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

+ +
+ + + + + + + + +
Warning
+

Currently external filters are executed with + Privoxy'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}
+
+
+
+
+
+
+

8.5.14. fast-redirects

+ "FAST-REDIRECTS">8.5.15. fast-redirects
@@ -2123,7 +2215,7 @@ problem-host.example.com
-

8.5.15. +

8.5.16. filter

@@ -2597,7 +2689,7 @@ problem-host.example.com

8.5.16. force-text-mode

+ "FORCE-TEXT-MODE">8.5.17. force-text-mode

@@ -2678,7 +2770,7 @@ problem-host.example.com

8.5.17. forward-override

+ "FORWARD-OVERRIDE">8.5.18. forward-override
@@ -2811,7 +2903,7 @@ TAG:^User-Agent: fetch libfetch/2\.0$

8.5.18. handle-as-empty-document

+ "HANDLE-AS-EMPTY-DOCUMENT">8.5.19. handle-as-empty-document
@@ -2889,7 +2981,7 @@ example.org/.*\.js$

8.5.19. handle-as-image

+ "HANDLE-AS-IMAGE">8.5.20. handle-as-image
@@ -2978,7 +3070,7 @@ nasty-banner-server.example.com/junk.cgi\?output=trash

8.5.20. hide-accept-language

+ "HIDE-ACCEPT-LANGUAGE">8.5.21. hide-accept-language
@@ -3058,7 +3150,7 @@ nasty-banner-server.example.com/junk.cgi\?output=trash

8.5.21. hide-content-disposition

+ "HIDE-CONTENT-DISPOSITION">8.5.22. hide-content-disposition
@@ -3144,7 +3236,7 @@ nasty-banner-server.example.com/junk.cgi\?output=trash

8.5.22. hide-if-modified-since

+ "HIDE-IF-MODIFIED-SINCE">8.5.23. hide-if-modified-since
@@ -3231,7 +3323,7 @@ nasty-banner-server.example.com/junk.cgi\?output=trash

8.5.23. hide-from-header

+ "HIDE-FROM-HEADER">8.5.24. hide-from-header
@@ -3306,7 +3398,7 @@ nasty-banner-server.example.com/junk.cgi\?output=trash
-

8.5.24. +

8.5.25. hide-referrer

@@ -3426,7 +3518,7 @@ nasty-banner-server.example.com/junk.cgi\?output=trash

8.5.25. hide-user-agent

+ "HIDE-USER-AGENT">8.5.26. hide-user-agent

@@ -3515,7 +3607,7 @@ nasty-banner-server.example.com/junk.cgi\?output=trash
-

8.5.26. +

8.5.27. limit-connect

@@ -3596,7 +3688,7 @@ nasty-banner-server.example.com/junk.cgi\?output=trash

8.5.27. limit-cookie-lifetime

+ "LIMIT-COOKIE-LIFETIME">8.5.28. limit-cookie-lifetime

@@ -3678,7 +3770,7 @@ nasty-banner-server.example.com/junk.cgi\?output=trash

8.5.28. prevent-compression

+ "PREVENT-COMPRESSION">8.5.29. prevent-compression
@@ -3782,7 +3874,7 @@ nasty-banner-server.example.com/junk.cgi\?output=trash

8.5.29. overwrite-last-modified

+ "OVERWRITE-LAST-MODIFIED">8.5.30. overwrite-last-modified
@@ -3878,7 +3970,7 @@ nasty-banner-server.example.com/junk.cgi\?output=trash
-

8.5.30. +

8.5.31. redirect

@@ -3982,7 +4074,7 @@ www.privoxy.org/user-manual/

8.5.31. server-header-filter

+ "SERVER-HEADER-FILTER">8.5.32. server-header-filter

@@ -4054,7 +4146,7 @@ example.org/instance-that-is-delivered-as-xml-but-is-not

8.5.32. server-header-tagger

+ "SERVER-HEADER-TAGGER">8.5.33. server-header-tagger
@@ -4127,7 +4219,7 @@ example.org/instance-that-is-delivered-as-xml-but-is-not

8.5.33. session-cookies-only

+ "SESSION-COOKIES-ONLY">8.5.34. session-cookies-only
@@ -4225,7 +4317,7 @@ example.org/instance-that-is-delivered-as-xml-but-is-not

8.5.34. set-image-blocker

+ "SET-IMAGE-BLOCKER">8.5.35. set-image-blocker
@@ -4364,7 +4456,7 @@ example.org/instance-that-is-delivered-as-xml-but-is-not
-

8.5.35. +

8.5.36. Summary

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:

-

8.7.1. +

8.7.1. match-all.action

Remember all actions @@ -4572,7 +4664,7 @@ example.org/instance-that-is-delivered-as-xml-but-is-not

-

8.7.2. +

8.7.2. default.action

If you aren't a developer, there's no need for you to edit the @@ -4915,7 +5007,7 @@ wiki.

-

8.7.3. +

8.7.3. user.action

So far we are painting with a broad brush by setting general diff --git a/doc/webserver/user-manual/appendix.html b/doc/webserver/user-manual/appendix.html index 54fb4765..34cf2ecf 100644 --- a/doc/webserver/user-manual/appendix.html +++ b/doc/webserver/user-manual/appendix.html @@ -293,7 +293,7 @@

-

14.2. Privoxy's +

14.2. Privoxy's Internal Pages

Since Privoxy proxies each @@ -313,7 +313,7 @@

+ +
+

9.3. 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 + Privoxy 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.

+ +

Privoxy 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
+
+
+ +
+ + + + + + + + +
Warning
+

Currently external filters are executed with Privoxy's privileges! Only use external + filters you understand and trust.

+
+
+ +

External filters are experimental and the syntax may change in the + future.

+
diff --git a/doc/webserver/user-manual/index.html b/doc/webserver/user-manual/index.html index 3746844f..c1c1df77 100644 --- a/doc/webserver/user-manual/index.html +++ b/doc/webserver/user-manual/index.html @@ -20,10 +20,10 @@ Manual

Copyright © - 2001-2013 by Privoxy + 2001-2014 by Privoxy Developers

-

$Id: user-manual.sgml,v 2.182 2014/05/05 10:08:43 +

$Id: user-manual.sgml,v 2.183 2014/05/26 10:48:39 fabiankeil Exp $

@@ -213,17 +213,20 @@
7.2.2. templdir
-
7.2.3. logdir
+
7.2.3. temporary-directory
-
7.2.4. actionsfile
+
7.2.4. logdir
7.2.5. actionsfile
+ +
7.2.6. filterfile
-
7.2.6. logfile
+
7.2.7. logfile
-
7.2.7. trustfile
+
7.2.8. trustfile
@@ -345,10 +348,10 @@
-
8.1. Finding the Right +
8.1. Finding the Right Mix
-
8.2. How to Edit
+
8.2. How to Edit
8.3. How Actions are Applied to Requests
@@ -361,7 +364,7 @@
8.4.1. The Host Pattern
-
8.4.2. The Path +
8.4.2. The Path Pattern
8.4.3. The Tag @@ -416,70 +419,73 @@ "actions-file.html#DOWNGRADE-HTTP-VERSION">downgrade-http-version
8.5.14. fast-redirects
+ "actions-file.html#EXTERNAL-FILTER">external-filter
8.5.15. filter
+ "actions-file.html#FAST-REDIRECTS">fast-redirects
8.5.16. force-text-mode
+ "actions-file.html#FILTER">filter
8.5.17. forward-override
+ "actions-file.html#FORCE-TEXT-MODE">force-text-mode
8.5.18. handle-as-empty-document
+ "actions-file.html#FORWARD-OVERRIDE">forward-override
8.5.19. handle-as-image
+ "actions-file.html#HANDLE-AS-EMPTY-DOCUMENT">handle-as-empty-document
8.5.20. hide-accept-language
+ "actions-file.html#HANDLE-AS-IMAGE">handle-as-image
8.5.21. hide-content-disposition
+ "actions-file.html#HIDE-ACCEPT-LANGUAGE">hide-accept-language
8.5.22. hide-if-modified-since
+ "actions-file.html#HIDE-CONTENT-DISPOSITION">hide-content-disposition
8.5.23. hide-from-header
+ "actions-file.html#HIDE-IF-MODIFIED-SINCE">hide-if-modified-since
8.5.24. hide-referrer
+ "actions-file.html#HIDE-FROM-HEADER">hide-from-header
8.5.25. hide-user-agent
+ "actions-file.html#HIDE-REFERRER">hide-referrer
8.5.26. limit-connect
+ "actions-file.html#HIDE-USER-AGENT">hide-user-agent
8.5.27. limit-cookie-lifetime
+ "actions-file.html#LIMIT-CONNECT">limit-connect
8.5.28. prevent-compression
+ "actions-file.html#LIMIT-COOKIE-LIFETIME">limit-cookie-lifetime
8.5.29. overwrite-last-modified
+ "actions-file.html#PREVENT-COMPRESSION">prevent-compression
8.5.30. redirect
+ "actions-file.html#OVERWRITE-LAST-MODIFIED">overwrite-last-modified
8.5.31. server-header-filter
+ "actions-file.html#REDIRECT">redirect
8.5.32. server-header-tagger
+ "actions-file.html#SERVER-HEADER-FILTER">server-header-filter
8.5.33. session-cookies-only
+ "actions-file.html#SERVER-HEADER-TAGGER">server-header-tagger
8.5.34. set-image-blocker
+ "actions-file.html#SESSION-COOKIES-ONLY">session-cookies-only
8.5.35. Summary
+ "actions-file.html#SET-IMAGE-BLOCKER">set-image-blocker + +
8.5.36. Summary
@@ -491,13 +497,13 @@
8.7.1. match-all.action
+ "actions-file.html#AEN4982">match-all.action
8.7.2. default.action
+ "actions-file.html#AEN5004">default.action
8.7.3. user.action
+ "actions-file.html#AEN5117">user.action
@@ -507,11 +513,15 @@
-
9.1. Filter File +
9.1. Filter File Tutorial
9.2. The Pre-defined Filters
+ +
9.3. External filter + syntax
@@ -571,7 +581,7 @@
14.1. Regular Expressions
-
14.2. Privoxy's Internal +
14.2. Privoxy's Internal Pages
-- 2.49.0