From b0c1fb7d3a76e773386536c3ae92105a75bf90be Mon Sep 17 00:00:00 2001 From: hal9 Date: Thu, 25 Apr 2002 22:43:18 +0000 Subject: [PATCH] More cleanup for recent changes, and otherwise. Fixed broken links, what happened to config/edit-actions? HTMLized the sample output from CGI page. --- doc/source/user-manual.sgml | 182 ++++++++++++++++++++---------------- 1 file changed, 103 insertions(+), 79 deletions(-) diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml index 686c1cf2..c75aa4a7 100644 --- a/doc/source/user-manual.sgml +++ b/doc/source/user-manual.sgml @@ -25,7 +25,7 @@ This file belongs into ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/ - $Id: user-manual.sgml,v 1.91 2002/04/24 02:39:31 hal9 Exp $ + $Id: user-manual.sgml,v 1.92 2002/04/25 18:55:13 hal9 Exp $ Written by and Copyright (C) 2001 the SourceForge Privoxy team. http://www.privoxy.org/ @@ -46,7 +46,7 @@ Privoxy User Manual -$Id: user-manual.sgml,v 1.91 2002/04/24 02:39:31 hal9 Exp $ +$Id: user-manual.sgml,v 1.92 2002/04/25 18:55:13 hal9 Exp $ @@ -478,22 +478,22 @@ - You will probably want to keep an eye out for sites that require persistent - cookies, and add these to your actions configuration as needed. By + You will probably want to keep an eye out for sites for which you may prefer + persistent cookies, and add these to your actions configuration as needed. By default, most of these will be accepted only during the current browser - session (aka session cookies), until you add them to the + session (aka session cookies), unless you add them to the configuration. If you want the browser to handle this instead, you will need to edit user.action (or through the web based interface) - and disable this feature. If you use more than one browser, it would make more - sense to let Privoxy handle this. In which case, - the browser(s) should be set to accept all cookies. + and disable this feature. If you use more than one browser, it would make + more sense to let Privoxy handle this. In which + case, the browser(s) should be set to accept all cookies. Another feature where you will probably want to define exceptions for trusted sites is the popup-killing (through the +popup and +filter{popups} actions), because your favorite shopping, - banking, or leisure site may need popups. + banking, or leisure site may need popups (explained below). @@ -550,7 +550,7 @@ If you can't get rid of the problem at all, think you've found a bug in Privoxy, want to propose a new feature or smarter rules, please see the - chapter Contacting the + section Contacting the Developers below. @@ -647,7 +647,6 @@ in text files. These files can be edited with a text editor. Many important aspects of Privoxy can also be controlled easily with a web browser. - @@ -664,19 +663,31 @@ - - - -Privoxy Menu: + + + + Privoxy Menu - * View & change the current configuration - * View the source code version numbers - * View the request headers. - * Look up which actions apply to a URL and why - * Toggle Privoxy on or off + + +         ▪  View & change the current configuration + + +         ▪  View the source code version numbers + + +         ▪  View the request headers. + + +         ▪  Look up which actions apply to a URL and why + + +         ▪  Toggle Privoxy on or off + + + + - - This should be self-explanatory. Note the first item leads to an editor for the @@ -729,7 +740,7 @@ Privoxy Menu: - The main configuration file is named config + The main configuration file is named config on Linux, Unix, BSD, OS/2, and AmigaOS and config.txt on Windows. This is a required file. @@ -737,7 +748,7 @@ Privoxy Menu: - default.action (the main actions file) is used to define + default.action (the main actions file) is used to define the default settings for various actions relating to images, banners, pop-ups, access restrictions, banners and cookies. @@ -751,21 +762,22 @@ Privoxy Menu: for Privoxy's internal use. - There is also a web based editor for this file that can be accessed at + There is also a web based editor that can be accessed from http://config.privoxy.org/edit-actions/ + url="http://config.privoxy.org/show-status/">http://config.privoxy.org/show-status/ (Shortcut: http://p.p/edit-actions/) for the + url="http://p.p/show-status/">http://p.p/show-status/) for the various actions files. - default.filter (the filter file) can be used to re-write the raw - page content, including viewable text as well as embedded HTML and JavaScript, - and whatever else lurks on any given web page. The filtering jobs are only - pre-defined here; whether to apply them or not is up to the actions files. + default.filter (the filter + file) can be used to re-write the raw page content, including + viewable text as well as embedded HTML and JavaScript, and whatever else + lurks on any given web page. The filtering jobs are only pre-defined here; + whether to apply them or not is up to the actions files. @@ -962,7 +974,7 @@ actionsfile Specifies: - The actions file(s) to use + The actions file(s) to use @@ -1022,7 +1034,7 @@ actionsfile Specifies: - The filter file to use + The filter file to use @@ -1720,7 +1732,7 @@ actionsfile Specifies: - Whether or not the web-based actions + Whether or not the web-based actions file editor may be used @@ -2427,12 +2439,14 @@ forward-socks4 and forward-socks4a the default policies. standard.action is used by Privoxy and the web based editor to set pre-defined values (and normally should not be edited). Local exceptions - are best done in user.action. - + are best done in user.action. The content of these + can all be viewed and edited from http://config.privoxy.org/show-status. + Anything you want can blocked, including ads, banners, or just some obnoxious - URL that you would rather not see. Cookies can be accepted or rejected, or + URL that you would rather not see is done here. Cookies can be accepted or rejected, or accepted only during the current browser session (i.e. not written to disk), content can be modified, JavaScripts tamed, user-tracking fooled, and much more. See below for a complete list of available actions. @@ -2450,16 +2464,16 @@ forward-socks4 and forward-socks4a Finding the Right Mix - Note that some actions like cookie suppression or script disabling may - render some sites unusable, which rely on these techniques to work properly. - Finding the right mix of actions is not easy and certainly a matter of personal - taste. In general, it can be said that the more aggressive - your default settings (in the top section of the actions file) are, - the more exceptions for trusted sites you will have to - make later. If, for example, you want to kill popup windows per default, you'll - have to make exceptions from that rule for sites that you regularly use - and that require popups for actually useful content, like maybe your bank, - favorite shop, or newspaper. + Note that some actions like cookie suppression + or script disabling may render some sites unusable, which rely on these + techniques to work properly. Finding the right mix of actions is not easy and + certainly a matter of personal taste. In general, it can be said that the more + aggressive your default settings (in the top section of the + actions file) are, the more exceptions for trusted sites you + will have to make later. If, for example, you want to kill popup windows per + default, you'll have to make exceptions from that rule for sites that you + regularly use and that require popups for actually useful content, like maybe + your bank, favorite shop, or newspaper. @@ -2475,8 +2489,8 @@ forward-socks4 and forward-socks4a How to Edit The easiest way to edit the actions files is with a browser by - using our browser-based editor, which is available at http://config.privoxy.org/edit-actions. + using our browser-based editor, which can be reached from http://config.privoxy.org/show-status. @@ -2490,7 +2504,7 @@ forward-socks4 and forward-socks4a How Actions are Applied to URLs Actions files are divided into sections. There are special sections, - like the alias sections which will be discussed later. For now + like the alias sections which will be discussed later. For now let's concentrate on regular sections: They have a heading line (often split up to multiple lines for readability) which consist of a list of actions, separated by whitespace and enclosed in curly braces. Below that, there @@ -2502,7 +2516,11 @@ forward-socks4 and forward-socks4a compared to all patterns in this file. Every time it matches, the list of applicable actions for the URL is incrementally updated, using the heading of the section in which the pattern is located. If multiple matches for - the same URL set the same action differently, the last match wins. + the same URL set the same action differently, the last match wins. If not, + the effects are aggregated (e.g. a URL might match both the + +handle-as-image + and +block actions). + @@ -2920,12 +2938,15 @@ forward-socks4 and forward-socks4a instead. If there is sufficient space, a large red banner will appear with a friendly message about why the page was blocked, and a way to go there anyway. If there is insufficient space a smaller blocked page will appear - without the red banner. + without the red banner. + Click here + to view the default blocked HTML page (Privoxy must be running + for this to work as intended!). - A very important exception is if the URL matches both +block - and matches both + +block and +handle-as-image, then it will be handled by +set-image-blocker @@ -2934,7 +2955,8 @@ forward-socks4 and forward-socks4a ads and other objectionable content. - The +filter action can also perform some of the + The +filter + action can also perform some of the same functionality as +block, but by virtue of very different programming techniques, and is most often used for different reasons. @@ -3257,8 +3279,9 @@ forward-socks4 and forward-socks4a Filtering can achieve some of the effects as the +block action, i.e. it can be used to block ads and banners. In the overall - scheme of things, filtering is one of the last things Privoxy - does with a web page. So other actions are applied first. + scheme of things, filtering is one of the first things Privoxy + does with a web page. So other most other actions are applied to the + already filtered page. @@ -3368,7 +3391,8 @@ forward-socks4 and forward-socks4a The keyword block will completely remove the header - (not to be confused with the +block action). + (not to be confused with the +block action). Alternately, you can specify any value you prefer to send to the web server. @@ -3549,13 +3573,17 @@ forward-socks4 and forward-socks4a This only has meaning if the URL (or pattern) also is - +blocked, in which case a blocked image can - be sent rather than a HTML page. (See - +set-image-blocker - below for control over what will actually be displayed by the browser.) + +blocked, in which case a user definable image can + be sent rather than a HTML page. This is integral to the whole concept of + ad blocking: the URL must match both a +block rule, + and +handle-as-image. + (See +set-image-blocker + below for control over what will actually be displayed by the browser.) - There is little reason to change the default definition for this. + There is little reason to change the default definition for this action. @@ -4864,7 +4892,8 @@ Requests - Show information about the current configuration: + Show information about the current configuration, including viewing and + editing of actions files:
@@ -4886,7 +4915,7 @@ Requests - Show the client's request headers: + Show the browser's request headers:
@@ -4930,17 +4959,6 @@ Requests
- - - - Edit the actions list file: - -
- - http://config.privoxy.org/edit-actions - -
- @@ -5033,7 +5051,7 @@ Requests First, your web browser requests a web page. The browser knows to send the request to Privoxy, who in turn, - will relay the request to the remote web server after passing a few quick + will relay the request to the remote web server after passing the following tests: @@ -5117,8 +5135,10 @@ Requests Anatomy of an Action - The way Privoxy applies actions - and filters to any given URL can be complex, and not always so + The way Privoxy applies + actions + and filters + to any given URL can be complex, and not always so easy to understand what is happening. And sometimes we need to be able to see just what Privoxy is doing. Especially, if something Privoxy is doing @@ -5430,6 +5450,10 @@ Requests Temple Place - Suite 330, Boston, MA 02111-1307, USA. $Log: user-manual.sgml,v $ + Revision 1.92 2002/04/25 18:55:13 hal9 + More catchups on new actions files, and new actions names. + Other assorted cleanups, and minor modifications. + Revision 1.91 2002/04/24 02:39:31 hal9 Add 'Chain of Events' section. -- 2.39.2