From 38cc6e90b4e805ca1b4e7e0f5bdd23a73e5162a4 Mon Sep 17 00:00:00 2001 From: oes Date: Tue, 14 May 2002 17:23:11 +0000 Subject: [PATCH] Renamed the prevent-*-cookies actions, extended aliases section and moved it before the example AFs --- doc/source/user-manual.sgml | 266 ++++++++++++++++++++---------------- 1 file changed, 145 insertions(+), 121 deletions(-) diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index 95af6626..9f8e3245 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -27,7 +27,7 @@ This file belongs into ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/ - $Id: user-manual.sgml,v 1.107 2002/05/12 03:20:41 hal9 Exp $ + $Id: user-manual.sgml,v 1.108 2002/05/14 15:29:12 oes Exp $ Copyright (C) 2001, 2002 Privoxy Developers See LICENSE. @@ -53,7 +53,7 @@ -$Id: user-manual.sgml,v 1.107 2002/05/12 03:20:41 hal9 Exp $ +$Id: user-manual.sgml,v 1.108 2002/05/14 15:29:12 oes Exp $ - -<emphasis>prevent-reading-cookies</emphasis> + +<emphasis>crunch-outgoing-cookies</emphasis> @@ -4310,7 +4310,7 @@ www.pclinuxonline.com This action is only concerned with outgoing cookies. For incoming cookies, use - prevent-setting-cookies. + crunch-incoming-cookies. Use both to disable cookies completely. @@ -4325,7 +4325,7 @@ www.pclinuxonline.com Example usage: - +prevent-reading-cookies + +crunch-outgoing-cookies @@ -4335,8 +4335,8 @@ www.pclinuxonline.com - -<emphasis>prevent-setting-cookies</emphasis> + +<emphasis>crunch-incoming-cookies</emphasis> @@ -4380,7 +4380,7 @@ www.pclinuxonline.com This action is only concerned with incoming cookies. For outgoing cookies, use - prevent-reading-cookies. + crunch-outgoing-cookies. Use both to disable cookies completely. @@ -4395,7 +4395,7 @@ www.pclinuxonline.com Example usage: - +prevent-setting-cookies + +crunch-incoming-cookies @@ -4448,8 +4448,8 @@ www.pclinuxonline.com Notes: - This is less strict than prevent-setting-cookies / - prevent-reading-cookies and allows you to browse + This is less strict than crunch-incoming-cookies / + crunch-outgoing-cookies and allows you to browse websites that insist or rely on setting cookies, without compromising your privacy too badly. @@ -4461,17 +4461,14 @@ www.pclinuxonline.com It makes no sense at all to use session-cookies-only - together with prevent-setting-cookies or - prevent-reading-cookies. If you do, cookies + together with crunch-incoming-cookies or + crunch-outgoing-cookies. If you do, cookies will be plainly killed. Note that it is up to the browser how it handles such cookies without an expires field. If you use an exotic browser, you might want to try it out to be sure. - - prevent-keeping-cookies is an alternate name for this action. - @@ -4745,10 +4742,120 @@ my-internal-testing-server.void actions. + + + + +Aliases + + Custom actions, known to Privoxy + as aliases, can be defined by combining other actions. + These can in turn be invoked just like the built-in actions. + Currently, an alias name can contain any character except space, tab, + =, + { and }, but we strongly + recommend that you only use a to z, + 0 to 9, +, and -. + Alias names are not case sensitive, and are not required to start with a + + or - sign, since they are merely textually + expanded. + + + Aliases can be used throughout the actions file, but they must be + defined in a special section at the top of the file! + And there can only be one such section per actions file. Each actions file may + have its own alias section, and the aliases defined in it are only visible + within that file. + + + There are two main reasons to use aliases: One is to save typing for frequently + used combinations of actions, the other one is a gain in flexibility: If you + decide once how you want to handle shops by defining an alias called + shop, you can later chenge your policy on shops in + one place, and your changes will take effect everywhere + in the actions file where the shop alias is used. Calling aliases + by their purpose also makes your actions files more readable. + + + Currently, there is one big drawback to using aliases, though: + Privoxy's built-in web-based action file + editor honors aliases when reading the actions files, but it expands + them before writing. So the effects of your aliases are of course preserved, + but the aliases themselves are lost when you edit the files this way. + This is likely to change in future versions of Privoxy. + + + + Now let's define some aliases... + + + + + # Useful custom aliases we can use later. + # + # Note the (required!) section header line and that this section + # must be at the top of the actions file! + # + {{alias}} + + # These aliases just save typing later: + # + +crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies + -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies + +imageblock = +block +handle-as-image + + # These aliases define combinations of actions + # that are useful for certain types of sites: + # + fragile = -block -crunch-all-cookies -filter -fast-redirects -hide-referer -kill-popups + shop = -crunch-all-cookies -fast-redirects + + # Aliases defined from other aliases, for really lazy people ;-) + # + c0 = +crunch-all-cookies + c1 = -crunch-all-cookies + + + + ...and put them to use. These sections would appear in the lower part of an + actions file and define exceptions to the default actions (as specified further + up for the / pattern): + + + + + # These sites are either very complex or very keen on + # user data and require minimal interference to work: + # + {fragile} + .office.microsoft.com + .windowsupdate.microsoft.com + .nytimes.com + + # Shopping sites: + # Allow cookies (for setting and retrieving your customer data) + # + {shop} + .quietpc.com + .worldpay.com # for quietpc.com + .scan.co.uk + + # These shops require pop-ups: + # + {shop -kill-popups -filter{popups}} + .dabs.com + .overclockers.co.uk + + + Aliases like shop and fragile are often used for + problem sites that require some actions to be disabled + in order to function properly. + + - + Sample Actions Files Remember that the meaning of any of the above references is reversed by preceding @@ -4795,7 +4902,7 @@ for-privoxy-version=3.0 # Some useful aliases. # Alias to turn off cookie handling, ie allow all cookies unmolested. - -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies \ + -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies \ -session-cookies-only # Alias to both block and treat as if an image for ad blocking @@ -4804,10 +4911,10 @@ for-privoxy-version=3.0 # Fragile sites should have the minimum changes: fragile = -block -deanimate-gifs -fast-redirects -filter -hide-referer \ - -prevent-cookies -kill-popups + -crunch-all-cookies -kill-popups # Shops should be allowed to set persistent cookies - shop = -filter -prevent-cookies -session-cookies-only + shop = -filter -crunch-all-cookies -session-cookies-only ########################################################################## @@ -4845,8 +4952,8 @@ for-privoxy-version=3.0 -limit-connect \ +prevent-compression \ -session-cookies-only \ - -prevent-reading-cookies \ - -prevent-setting-cookies \ + -crunch-outgoing-cookies \ + -crunch-incoming-cookies \ -kill-popups \ -send-vanilla-wafer \ -send-wafer \ @@ -4984,20 +5091,20 @@ for-privoxy-version=3.0 # Any aliases you want to use need to be re-defined here. # Alias to turn off cookie handling, ie allow all cookies unmolested. - -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies \ - -session-cookies-only + -crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies \ + -session-cookies-only # Fragile sites should have the minimum changes: fragile = -block -deanimate-gifs -fast-redirects -filter -hide-referer \ - -prevent-cookies -kill-popups + -crunch-all-cookies -kill-popups # Allow persistent cookies for a few regular sites that we # trust via our above alias. These will be saved from one browser session # to the next. We are explicity turning off any and all cookie handling, -# even though the prevent-*-cookie settings were disabled in our above +# even though the cunch-*-cookies settings were disabled in our above # default.action anyway. So cookies from these domains will come through # unmolested. - { -prevent-cookies } + { -crunch-all-cookies } .sun.com .yahoo.com .msdn.microsoft.com @@ -5028,98 +5135,12 @@ for-privoxy-version=3.0 - - - - -Aliases - - Custom actions, known to Privoxy - as aliases, can be defined by combining other actions. - These can in turn be invoked just like the built-in actions. - Currently, an alias can contain any character except space, tab, =, - { or }. But please use only a- - z, 0-9, +, and - -. Alias names are not case sensitive, and - must be defined before other actions in the - actions file! And there can only be one set of aliases - defined per file. Each actions file may have its own aliases, but they are - only visible within that file. Aliases do not requir a + or - - sign in front, since they are merely expanded. - - - - Now let's define a few aliases: - - - - - - - # Useful custom aliases we can use later. These must come first! - {{alias}} - +prevent-cookies = +prevent-setting-cookies +prevent-reading-cookies - -prevent-cookies = -prevent-setting-cookies -prevent-reading-cookies - fragile = -block -prevent-cookies -filter -fast-redirects -hide-referer -kill-popups - shop = -prevent-cookies -filter -fast-redirects - +imageblock = +block +handle-as-image - - # Aliases defined from other aliases, for people who don't like to type - # too much: ;-) - c0 = +prevent-cookies - c1 = -prevent-cookies - #... etc. Customize to your heart's content. - - - - - - - Some examples using our shop and fragile - aliases from above. These would appear in the lower sections of an - actions file as exceptions to the default actions (as defined in the - upper section): - - - - - - - # These sites are very complex and require - # minimal interference. - {fragile} - .office.microsoft.com - .windowsupdate.microsoft.com - .nytimes.com - - # Shopping sites - but we still want to block ads. - {shop} - .quietpc.com - .worldpay.com # for quietpc.com - .scan.co.uk - - # These shops require pop-ups also - {shop -kill-popups} - .dabs.com - .overclockers.co.uk - - - - - - The shop and fragile aliases are often used for - problem sites that require most actions to be disabled - in order to function properly. - - - - @@ -5846,7 +5867,7 @@ Requests First, the server headers are read and processed to determine, among other things, the MIME type (document type) and encoding. The headers are then filtered as deterimed by the - +prevent-setting-cookies, + +crunch-incoming-cookies, +session-cookies-only, and +downgrade-http-version actions. @@ -5967,8 +5988,8 @@ Requests +filter{webbugs} +filter{refresh-tags} +filter{nimda} +filter{banners-by-size} +hide-forwarded-for-headers +hide-from-header{block} +hide-referer{forge} -hide-user-agent -handle-as-image +set-image-blocker{pattern} -limit-connect - +prevent-compression +session-cookies-only -prevent-reading-cookies - -prevent-setting-cookies -kill-popups -send-vanilla-wafer -send-wafer } + +prevent-compression +session-cookies-only -crunch-outgoing-cookies + -crunch-incoming-cookies -kill-popups -send-vanilla-wafer -send-wafer } / { -session-cookies-only } @@ -6037,8 +6058,8 @@ Requests +filter{webbugs} +filter{refresh-tags} +filter{nimda} +filter{banners-by-size} +hide-forwarded-for-headers +hide-from-header{block} +hide-referer{forge} -hide-user-agent -handle-as-image +set-image-blocker{pattern} -limit-connect - +prevent-compression -session-cookies-only -prevent-reading-cookies - -prevent-setting-cookies -kill-popups -send-vanilla-wafer -send-wafer + +prevent-compression -session-cookies-only -crunch-outgoing-cookies + -crunch-incoming-cookies -kill-popups -send-vanilla-wafer -send-wafer @@ -6105,8 +6126,8 @@ Requests +filter{webbugs} +filter{nimda} +filter{banners-by-size} +filter{hal} +filter{fun} +hide-forwarded-for-headers +hide-from-header{block} +hide-referer{forge} -hide-user-agent -handle-as-image +set-image-blocker{blank} - +prevent-compression +session-cookies-only -prevent-setting-cookies - -prevent-reading-cookies +kill-popups -send-vanilla-wafer -send-wafer } + +prevent-compression +session-cookies-only -crunch-incoming-cookies + -crunch-outgoing-cookies +kill-popups -send-vanilla-wafer -send-wafer } / { +block +handle-as-image } @@ -6221,6 +6242,9 @@ Requests Temple Place - Suite 330, Boston, MA 02111-1307, USA. $Log: user-manual.sgml,v $ + Revision 1.108 2002/05/14 15:29:12 oes + Completed proofreading the actions chapter + Revision 1.107 2002/05/12 03:20:41 hal9 Small clarifications for 127.0.0.1 vs localhost for listen-address since this apparently an important distinction for some OS's. -- 2.39.2