X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fuser-manual.sgml;h=dee740570d8f705c673f79828541199c35ed8986;hp=30d3b3ec5b28a99538422ec2bacb9308360ac3dc;hb=d09495686ceb54f830dfecefcdfdde1061cc8f33;hpb=37db7e929d9268dcdbe34c6ce87d674e866f8d4e
diff --git a/doc/source/user-manual.sgml b/doc/source/user-manual.sgml
index 30d3b3ec..dee74057 100644
--- a/doc/source/user-manual.sgml
+++ b/doc/source/user-manual.sgml
@@ -12,10 +12,10 @@
-
+
-
-
+
+
@@ -33,7 +33,7 @@
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: user-manual.sgml,v 2.24 2006/10/03 11:13:54 hal9 Exp $
+ $Id: user-manual.sgml,v 2.26 2006/10/24 11:16:44 hal9 Exp $
Copyright (C) 2001- 2006 Privoxy Developers http://www.privoxy.org
See LICENSE.
@@ -59,7 +59,7 @@
-$Id: user-manual.sgml,v 2.24 2006/10/03 11:13:54 hal9 Exp $
+$Id: user-manual.sgml,v 2.26 2006/10/24 11:16:44 hal9 Exp $
-Red Hat, SuSE and Conectiva RPMs
+Red Hat and Fedora RPMs
RPMs can be installed with rpm -Uvh privoxy-&p-version;-1.rpm,
@@ -363,7 +363,8 @@ How to install the binary packages depends on your operating system:
The most convenient way to obtain the Privoxy sources
- is to download the source tarball from our project
+ is to download the source tarball from our
+ project download
page.
@@ -422,7 +423,7 @@ How to install the binary packages depends on your operating system:
What's New in this Release
- There are many improvements and new features since the last Privoxy stable release:
+ There are many improvements and new features since Privoxy 3.0.3, the last stable release:
@@ -576,39 +577,11 @@ How to install the binary packages depends on your operating system:
In addition, there are numerous bug fixes and significant enhancements,
including error pages should no longer be cached if the problem is fixed,
- much better DNS error handling, and various logging improvements.
+ much better DNS error handling, various logging improvements, and
+ configuration updates for better ad blocking and junk elimination.
-
-
- The default actions setting is now Cautious. Previous
- releases had a default setting of Medium. Experienced
- users may want to adjust this, as it is fairly conservative by &my-app;
- standards and past practices. See
- http://config.privoxy.org/edit-actions-list?f=default. New users
- should try the default settings for a while before turning up the volume.
-
-
- The default setting has filtering turned off, which
- subsequently means that compression is on. Remember
- that filtering does not work on compressed pages, so if you use, or want to
- use, filtering, you will need to force compression off. Example:
-
-
-
- { +filter{google} +prevent-compression }
- .google.
-
-
- Or if you use a number of filters, or filter many sites, you may just want
- to turn off compression for all sites in
- default.action (or
- user.action).
-
-
-
@@ -673,11 +646,53 @@ How to install the binary packages depends on your operating system:
default. This is primarily a matter of emphasis, but some features
you may have been used to, may now be off by default.
There are also a number of new actions and filters you may want to
- consider, most of which are not incorporated into the default settings as
- yet (see above).
+ consider, most of which are not fully incorporated into the default
+ settings as yet (see above).
-
+
+
+
+ The default actions setting is now Cautious. Previous
+ releases had a default setting of Medium. Experienced
+ users may want to adjust this, as it is fairly conservative by &my-app;
+ standards and past practices. See
+ http://config.privoxy.org/edit-actions-list?f=default. New users
+ should try the default settings for a while before turning up the volume.
+
+
+
+
+
+ The default setting has filtering turned off, which
+ subsequently means that compression is on. Remember
+ that filtering does not work on compressed pages, so if you use, or want to
+ use, filtering, you will need to force compression off. Example:
+
+
+
+ { +filter{google} +prevent-compression }
+ .google.
+
+
+ Or if you use a number of filters, or filter many sites, you may just want
+ to turn off compression for all sites in
+ default.action (or
+ user.action).
+
+
+
+
+
+
+ Also, session-cookies-only is
+ off by default now. If you've liked this feature in the past, you may want
+ to turn it back on in user.action now.
+
+
+
+
@@ -687,6 +702,7 @@ How to install the binary packages depends on your operating system:
+
@@ -822,7 +838,8 @@ How to install the binary packages depends on your operating system:
First a bit of a warning ... blocking ads is much like blocking SPAM: the
more aggressive you are about it, the more likely you are to block
- things that were not intended. So there is a trade off here. If you want
+ things that were not intended. And the more likely that some things
+ may not work as intended. So there is a trade off here. If you want
extreme ad free browsing, be prepared to deal with more
problem sites, and to spend more time adjusting the
configuration to solve these unintended consequences. In short, there is
@@ -835,7 +852,7 @@ How to install the binary packages depends on your operating system:
Secondly, a brief explanation of Privoxy's actions. Actions in this context, are
the directives we use to tell Privoxy to perform
- some task relating to HTTP transactions (i.e. web browsing). We tell
+ some task relating to WWW transactions (i.e. web browsing). We tell
Privoxy to take some action. Each
action has a unique name and function. While there are many potential
actions in Privoxy's
@@ -860,13 +877,17 @@ How to install the binary packages depends on your operating system:
original page's HTML content. An ad image for instance, is just an URL
embedded in the page somewhere. The image itself may be on the same server,
or a server somewhere else on the Internet. Complex web pages will have many
- such embedded URLs.
+ such embedded URLs. &my-app; can deal with each URL individually, so, for
+ instance, the main page text is not touched, but images from such-and-such
+ server are blocked.
- The actions we need to know about for ad blocking are: block, handle-as-image, and
+ linkend="handle-as-image">handle-as-image,
+ handle-as-empty-document,and
set-image-blocker:
@@ -875,12 +896,14 @@ How to install the binary packages depends on your operating system:
- block - this action stops
- any contact between your browser and any URL patterns that match this
- action's configuration. It can be used for blocking ads, but also anything
- that is determined to be unwanted. By itself, it simply stops any
- communication with the remote server and sends Privoxy's
- own built-in BLOCKED page instead to let you now what has happened.
+ block - this is perhaps
+ the single most used action, and is particularly important for ad blocking.
+ This action stops any contact between your browser and any URL patterns
+ that match this action's configuration. It can be used for blocking ads,
+ but also anything that is determined to be unwanted. By itself, it simply
+ stops any communication with the remote server and sends
+ Privoxy's own built-in BLOCKED page instead to
+ let you now what has happened (with some exceptions, see below).
@@ -900,6 +923,15 @@ How to install the binary packages depends on your operating system:
+
+
+ handle-as-empty-document -
+ sends an empty document instead of Privoxy's
+ normal BLOCKED HTML page. This is useful for file types that are neither
+ HTML nor images, such as blocking JavaScript files.
+
+
+
Actions Files Tutorial.
The ideas explained therein also apply to the web-based editor.
+
+ There are also various
+ filters that can be used for ad blocking
+ (filters are a special subset of actions). These
+ fall into the advanced usage category, and are explained in
+ depth in later sections.
+
@@ -1082,7 +1121,7 @@ How to install the binary packages depends on your operating system:
- With Firefox, this can be set under:
+ With Firefox, this is typically set under:
@@ -1090,6 +1129,15 @@ How to install the binary packages depends on your operating system:
+
+ Or optionally on some platforms:
+
+
+
+ Edit -> Preferences -> General -> Connection Settings -> Manual Proxy Configuration
+
+
+
With Netscape (and
@@ -1154,7 +1202,7 @@ How to install the binary packages depends on your operating system:
-Red Hat, Fedora and Conectiva
+Red Hat and Fedora
A default Red Hat installation may not start &my-app; upon boot. It will use
the file /etc/privoxy/config as its main configuration
@@ -1190,6 +1238,9 @@ How to install the binary packages depends on your operating system:
+
Windows
@@ -1631,7 +1682,7 @@ for details.
default.action (which you will most probably want
to define sooner or later) are probably best applied in
user.action, where you can preserve them across
- upgrades. standard.action is for
+ upgrades. standard.action is only for
Privoxy's internal use.
@@ -1773,7 +1824,7 @@ for details.
- standard.action - is used by the web based editor
+ standard.action - is used only by the web based editor
at
http://config.privoxy.org/edit-actions-list?f=default,
to set various pre-defined sets of rules for the default actions section
@@ -2255,7 +2306,7 @@ for details.
- While flexibile, this is not the sophistication of full regular expression based syntax.
+ While flexible, this is not the sophistication of full regular expression based syntax.
@@ -2766,7 +2817,7 @@ new action
# Check if www.example.net/ really uses valid XHTML
-{+content-type-overwrite {application/xml}}
+{ +content-type-overwrite{application/xml} }
www.example.net/
# but leave the content type unmodified if the URL looks like a style sheet
@@ -2856,7 +2907,7 @@ new action
# Block the non-existent "Privacy-Violation:" client header
-{+crunch-client-header {Privacy-Violation:}}
+{ +crunch-client-header{Privacy-Violation:} }
/
@@ -2938,9 +2989,9 @@ new action
# Let the browser revalidate cached documents without being tracked across sessions
-{+hide-if-modified-since {-60} \
-+overwrite-last-modified {randomize} \
-+crunch-if-none-match}
+{ +hide-if-modified-since{-60} \
+ +overwrite-last-modified{randomize} \
+ +crunch-if-none-match}
/
@@ -3092,7 +3143,7 @@ new action
# Crunch server headers that try to prevent caching
-{+crunch-server-header {no-cache}}
+{ +crunch-server-header{no-cache} }
/
@@ -3665,6 +3716,14 @@ problem-host.example.com+filter{xml-to-html} # Header filter to change the Content-Type from xml to html
+
+
+ +filter{no-ping} # Removes non-standard ping attributes from anchor and area tags
+
+
+
+ +filter{hide-tor-exit-notation} # Header filter to remove the Tor exit node notation in Host and Referer headers
+
@@ -3955,7 +4014,7 @@ new action
This action alone doesn't do anything noticeable. It just marks URLs.
If the block action also applies,
- the presence or absence of this mark decides whether an HTML blocked
+ the presence or absence of this mark decides whether an HTML BLOCKED
page, or an empty document will be sent to the client as a substitute for the blocked content.
The empty document isn't literally empty, but actually contains a single space.
@@ -3986,6 +4045,8 @@ new action
Some browsers complain about syntax errors if JavaScript documents
are blocked with Privoxy's
default HTML page; this option can be used to silence them.
+ And of course this action can also be used to eliminate the &my-app;
+ BLOCKED message in frames.
The content type for the empty document can be specified with
@@ -4262,10 +4323,10 @@ new action
# Disarm the download link in Sourceforge's patch tracker
-{-filter\
-+content-type-overwrite {text/plain}\
-+hide-content-disposition {block} }
-.sourceforge.net/tracker/download.php
+{ -filter \
+ +content-type-overwrite{text/plain}\
+ +hide-content-disposition{block} }
+ .sourceforge.net/tracker/download.php
@@ -4350,9 +4411,9 @@ new action
# Let the browser revalidate without being tracked across sessions
-{+hide-if-modified-since {-60}\
-+overwrite-last-modified {randomize}\
-+crunch-if-none-match}
+{ +hide-if-modified-since{-60} \
+ +overwrite-last-modified{randomize} \
+ +crunch-if-none-match}
/
@@ -5010,16 +5071,25 @@ new action
Example usage (sections):
- # Set default:
+
+# Selectively turn off compression, and enable a filter
#
-{+prevent-compression}
-/ # Match all sites
+{ +filter{tiny-textforms} +prevent-compression }
+# Match only these sites
+ .google.
+ sourceforge.net
+ sf.net
+
+# Or instead, we could set a universal default:
+#
+{ +prevent-compression }
+ / # Match all sites
-# Make exceptions for ill sites:
+# Then maybe make exceptions for ill-behaved sites:
#
-{-prevent-compression}
-www.debianhelp.org
-www.pclinuxonline.com
+{ -prevent-compression }
+ .debianhelp.org
+ www.pclinuxonline.com
@@ -5114,9 +5184,9 @@ new action
# Let the browser revalidate without being tracked across sessions
-{+hide-if-modified-since {-60}\
-+overwrite-last-modified {randomize}\
-+crunch-if-none-match}
+{ +hide-if-modified-since{-60} \
+ +overwrite-last-modified{randomize} \
+ +crunch-if-none-match}
/
@@ -5687,7 +5757,6 @@ new action
them before writing. So the effects of your aliases are of course preserved,
but the aliases themselves are lost when you edit sections that use aliases
with it.
- This is likely to change in future versions of Privoxy.
@@ -5709,12 +5778,13 @@ new action
+crunch-all-cookies = +crunch-incoming-cookies +crunch-outgoing-cookies
-crunch-all-cookies = -crunch-incoming-cookies -crunch-outgoing-cookies
+block-as-image = +block +handle-as-image
- mercy-for-cookies = -crunch-all-cookies -session-cookies-only -filter{content-cookies}
+ allow-all-cookies = -crunch-all-cookies -session-cookies-only -filter{content-cookies}
# These aliases define combinations of actions
# that are useful for certain types of sites:
#
- fragile = -block -filter -crunch-all-cookies -fast-redirects -hide-referrer -kill-popups
+ fragile = -block -filter -crunch-all-cookies -fast-redirects -hide-referrer -kill-popups -prevent-compression
+
shop = -crunch-all-cookies -filter{all-popups} -kill-popups
# Short names for other aliases, for really lazy people ;-)
@@ -5737,7 +5807,8 @@ new action
{fragile}
.office.microsoft.com
.windowsupdate.microsoft.com
- .nytimes.com
+ # Gmail is really mail.google.com, not gmail.com
+ mail.google.com
# Shopping sites:
# Allow cookies (for setting and retrieving your customer data)
@@ -5745,18 +5816,18 @@ new action
{shop}
.quietpc.com
.worldpay.com # for quietpc.com
- .scan.co.uk
+ mybank.example.com
# These shops require pop-ups:
#
- {shop -kill-popups -filter{all-popups}}
+ {-kill-popups -filter{all-popups} -filter{unsolicited-popups}}
.dabs.com
.overclockers.co.uk
- Aliases like shop and fragile are often used for
- problem sites that require some actions to be disabled
+ Aliases like shop and fragile are typically used for
+ problem sites that require more than one action to be disabled
in order to function properly.
@@ -5902,6 +5973,8 @@ that also explains why and how aliases are used:
-filter-blogspot \
-filter-xml-to-html \
-filter-html-to-xml \
+ -filter-no-ping \
+ -filter-hide-tor-exit-notation \
-force-text-mode \
-handle-as-empty-document \
-handle-as-image \
@@ -7178,6 +7251,7 @@ pre-defined filters for your convenience:
+
html-to-xml
@@ -7187,6 +7261,26 @@ pre-defined filters for your convenience:
+
+ no-ping
+
+
+ Removes the non-standard ping attribute from
+ anchor and area HTML tags.
+
+
+
+
+
+ hide-tor-exit-notation
+
+
+ Header filter to remove the Tor exit node notation
+ found in Host and Referer headers.
+
+
+
+