From: hal9 Date: Wed, 30 Aug 2006 11:15:22 +0000 (+0000) Subject: More work on the new actions, especially filter-*-headers, and What's New X-Git-Tag: v_3_0_5~124 X-Git-Url: http://www.privoxy.org/gitweb/%40user-manual%40%40actions-help-prefix%40HANDLE-AS-EMPTY-DOCUMENT?a=commitdiff_plain;h=01ef40fc50001c99d8a4457bf6501c72e22e43fc;p=privoxy.git More work on the new actions, especially filter-*-headers, and What's New section. User Manual is close to final form for 3.0.4 release. Some tinkering and proof reading left to do. --- diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index 70979575..2b5198ec 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -32,7 +32,7 @@ This file belongs into ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/ - $Id: user-manual.sgml,v 2.13 2006/08/22 11:04:59 hal9 Exp $ + $Id: user-manual.sgml,v 2.14 2006/08/29 10:59:36 hal9 Exp $ Copyright (C) 2001- 2006 Privoxy Developers See LICENSE. @@ -58,7 +58,7 @@ -$Id: user-manual.sgml,v 2.13 2006/08/22 11:04:59 hal9 Exp $ +$Id: user-manual.sgml,v 2.14 2006/08/29 10:59:36 hal9 Exp $ -crunch-server-header +crunch-client-header @@ -3110,7 +3133,8 @@ problem-host.example.com based substitutions. (Note: as of version 3.0.3 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.) + don't know.) By default, filtering works only on the document content + itself, not the headers. @@ -3295,6 +3319,192 @@ problem-host.example.com + + +filter-client-headers + + + + Typical use: + + + To apply filtering to the client's (browser's) headers + + + + + + Effect: + + Extend filtering capabilities to the client's headers, which + by default applies only to the document itself. + + + + + + Type: + + + Boolean. + + + + + Parameter: + + + N/A + + + + + + Notes: + + + Regular expressions can be used to filter headers as well. Check your + filters closely before activating this action, as it can easily lead to broken + requests. + + + These filters are applied to each header on its own, not to them + all at once. This makes it easier to diagnose problems, but on the downside + you can't write filters that only change header x if header y's value is + z. + + + The filters are used after the other header actions have finished and can + use their output as input. + + + + Whenever possible one should specify ^, + $, the whole header name and the colon, to make sure + the filter doesn't cause havoc to other headers or the + page itself. For example if you want to transform + Galeon User-Agents to + Firefox User-Agents you + shouldn't use: + + + +s@Galeon/\d\.\d\.\d @@ + + + but: + + +s@^(User-Agent:.*) Galeon/\d\.\d\.\d (Firefox/\d\.\d\.\d\.\d)$@$1 $2@ + + + + + + + Example usage (section): + + + +{+filter-client-headers +filter{test_filter}} +problem-host.example.com + + + + + + + + + + + +filter-server-headers + + + + Typical use: + + + To apply filtering to the server's headers + + + + + + Effect: + + Extend filtering capabilities to the server's headers, which + by default applies only to the document itself. + + + + + + Type: + + + Boolean. + + + + + Parameter: + + + N/A + + + + + + Notes: + + + Similar to filter-client-headers, but works on + the server instead. To filter both server and client, use both. + + + As with filter-client-headers, check your + filters before activating this action, as it can easily lead to broken + requests. + + + These filters are applied to each header on its own, not to them + all at once. This makes it easier to diagnose problems, but on the downside + you can't write filters that only change header x if header y's value is + z. + + + The filters are used after the other header actions have finished and can + use their output as input. + + + Remember too, whenever possible one should specify ^, + $, the whole header name and the colon, to make sure + the filter doesn't cause havoc to other headers or the + page itself. See above for example. + + + + + + + Example usage (section): + + + +{+filter-server-headers +filter{test_filter}} +problem-host.example.com + + + + + + + + + force-text-mode @@ -5838,15 +6048,15 @@ ar.atwola.com/ Filter Files - All text substitutions that can be invoked through the - filter action which - must first be defined in a filter file, such as - default.filter. Mulitple filter files can be - defined through the - filterfile config - option. The filters as supplied by the developers will be found in + On-the-fly text substitutions that can be invoked through the + filter action need + to be defined in a filter file. Once defined, they + can then be invoked as an action. Mulitple filter files can be + defined through the filterfile config directive. The filters + as supplied by the developers will be found in default.filter. It is recommended that any locally - defined or modified filters go in a separately defined file such as + defined or modified filters go in a separately defined file such as user.filter. @@ -5865,7 +6075,12 @@ ar.atwola.com/ HTML, JavaScript, CSS etc. (all text/* MIME types, except text/plain). Substitutions are made at the source level, so if you want to roll - your own filters, you should be familiar with HTML syntax. + your own filters, you should first be familiar with HTML syntax, + and, of course, regular expressions. By default, filters are only applied + to the document content, but can be extended to the headers with + the supplemental actions: + filter-client-headers and + filter-server-headers. @@ -6484,22 +6699,6 @@ pre-defined filters for your convenience: - - filter-server-headers - - - - - - - - filter-client-headers - - - - - -