+ # These aliases just save typing later:
+ # (Note that some already use other aliases!)
+ #
+ +crunch-all-cookies = +<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> +<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
+ -crunch-all-cookies = -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> -<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
+ block-as-image = +block +handle-as-image
+ mercy-for-cookies = -crunch-all-cookies -<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link>
+
+ # These aliases define combinations of actions
+ # that are useful for certain types of sites:
+ #
+ fragile = -<link linkend="BLOCK">block</link> -<link linkend="FILTER">filter</link> -crunch-all-cookies -<link linkend="FAST-REDIRECTS">fast-redirects</link> -<link linkend="HIDE-REFERER">hide-referrer</link> -<link linkend="KILL-POPUPS">kill-popups</link>
+ shop = -crunch-all-cookies -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link> -<link linkend="KILL-POPUPS">kill-popups</link>
+
+ # Short names for other aliases, for really lazy people ;-)
+ #
+ c0 = +crunch-all-cookies
+ c1 = -crunch-all-cookies</screen>
+</para>
+
+<para>
+ ...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 <quote>/</quote> pattern):
+</para>
+
+<para>
+ <screen>
+ # 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{all-popups}}
+ .dabs.com
+ .overclockers.co.uk</screen>
+</para>
+
+<para>
+ Aliases like <quote>shop</quote> and <quote>fragile</quote> are often used for
+ <quote>problem</quote> sites that require some actions to be disabled
+ in order to function properly.
+</para>
+</sect2>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="act-examples">
+<title>Actions Files Tutorial</title>
+<para>
+ The above chapters have shown <link linkend="actions-file">which actions files
+ there are and how they are organized</link>, how actions are <link
+ linkend="actions">specified</link> and <link linkend="actions-apply">applied
+ to URLs</link>, how <link linkend="af-patterns">patterns</link> work, and how to
+ define and use <link linkend="aliases">aliases</link>. Now, let's look at an
+ example <filename>default.action</filename> and <filename>user.action</filename>
+ file and see how all these pieces come together:
+</para>
+
+<sect3><title>default.action</title>
+
+<para>
+Every config file should start with a short comment stating its purpose:
+</para>
+
+<para>
+ <screen># Sample default.action file <developers@privoxy.org></screen>
+</para>
+
+<para>
+Then, since this is the <filename>default.action</filename> file, the
+first section is a special section for internal use that you needn't
+change or worry about:
+</para>
+
+<para>
+ <screen>
+##########################################################################
+# Settings -- Don't change! For internal Privoxy use ONLY.
+##########################################################################
+
+{{settings}}
+for-privoxy-version=3.0</screen>
+</para>
+
+<para>
+After that comes the (optional) alias section. We'll use the example
+section from the above <link linkend="aliases">chapter on aliases</link>,
+that also explains why and how aliases are used:
+</para>
+
+<para>
+ <screen>
+##########################################################################
+# Aliases
+##########################################################################
+{{alias}}
+
+ # These aliases just save typing later:
+ # (Note that some already use other aliases!)
+ #
+ +crunch-all-cookies = +<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> +<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
+ -crunch-all-cookies = -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> -<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link>
+ block-as-image = +block +handle-as-image
+ mercy-for-cookies = -crunch-all-cookies -<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link>
+
+ # These aliases define combinations of actions
+ # that are useful for certain types of sites:
+ #
+ fragile = -<link linkend="BLOCK">block</link> -<link linkend="FILTER">filter</link> -crunch-all-cookies -<link linkend="FAST-REDIRECTS">fast-redirects</link> -<link linkend="HIDE-REFERER">hide-referrer</link> -<link linkend="KILL-POPUPS">kill-popups</link>
+ shop = -crunch-all-cookies -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link> -<link linkend="KILL-POPUPS">kill-popups</link></screen>
+</para>
+
+<para>
+ Now come the regular sections, i.e. sets of actions, accompanied
+ by URL patterns to which they apply. Remember <emphasis>all actions
+ are disabled when matching starts</emphasis>, so we have to explicitly
+ enable the ones we want.
+</para>
+
+<para>
+ The first regular section is probably the most important. It has only
+ one pattern, <quote><literal>/</literal></quote>, but this pattern
+ <link linkend="af-patterns">matches all URLs</link>. Therefore, the
+ set of actions used in this <quote>default</quote> section <emphasis>will
+ be applied to all requests as a start</emphasis>. It can be partly or
+ wholly overridden by later matches further down this file, or in user.action,
+ but it will still be largely responsible for your overall browsing
+ experience.
+</para>
+
+<para>
+ Again, at the start of matching, all actions are disabled, so there is
+ no real need to disable any actions here, but we will do that nonetheless,
+ to have a complete listing for your reference. (Remember: a <quote>+</quote>
+ preceding the action name enables the action, a <quote>-</quote> disables!).
+ Also note how this long line has been made more readable by splitting it into
+ multiple lines with line continuation.
+</para>
+
+<para>
+ <screen>
+##########################################################################
+# "Defaults" section:
+##########################################################################
+ { \
+ -<link linkend="ADD-HEADER">add-header</link> \
+ -<link linkend="BLOCK">block</link> \
+ -<link linkend="CRUNCH-INCOMING-COOKIES">crunch-incoming-cookies</link> \
+ -<link linkend="CRUNCH-OUTGOING-COOKIES">crunch-outgoing-cookies</link> \
+ +<link linkend="DEANIMATE-GIFS">deanimate-gifs</link> \
+ -<link linkend="DOWNGRADE-HTTP-VERSION">downgrade-http-version</link> \
+ +<link linkend="FAST-REDIRECTS">fast-redirects</link> \
+ +<link linkend="FILTER-JS-ANNOYANCES">filter{js-annoyances}</link> \
+ -<link linkend="FILTER-JS-EVENTS">filter{js-events}</link> \
+ +<link linkend="FILTER-HTML-ANNOYANCES">filter{html-annoyances}</link> \
+ -<link linkend="FILTER-CONTENT-COOKIES">filter{content-cookies}</link> \
+ +<link linkend="FILTER-REFRESH-TAGS">filter{refresh-tags}</link> \
+ +<link linkend="FILTER-UNSOLICITED-POPUPS">filter{unsolicited-popups}</link> \
+ -<link linkend="FILTER-ALL-POPUPS">filter{all-popups}</link> \
+ +<link linkend="FILTER-IMG-REORDER">filter{img-reorder}</link> \
+ +<link linkend="FILTER-BANNERS-BY-SIZE">filter{banners-by-size}</link> \
+ -<link linkend="FILTER-BANNERS-BY-LINK">filter{banners-by-link}</link> \
+ +<link linkend="FILTER-WEBBUGS">filter{webbugs}</link> \
+ -<link linkend="FILTER-TINY-TEXTFORMS">filter{tiny-textforms}</link> \
+ +<link linkend="FILTER-JUMPING-WINDOWS">filter{jumping-windows}</link> \
+ -<link linkend="FILTER-FRAMESET-BORDERS">filter{frameset-borders}</link> \
+ -<link linkend="FILTER-DEMORONIZER">filter{demoronizer}</link> \
+ -<link linkend="FILTER-SHOCKWAVE-FLASH">filter{shockwave-flash}</link> \
+ -<link linkend="FILTER-QUICKTIME-KIOSKMODE">filter{quicktime-kioskmode}</link> \
+ -<link linkend="FILTER-FUN">filter{fun}</link> \
+ -<link linkend="FILTER-CRUDE-PARENTAL">filter{crude-parental}</link> \
+ +<link linkend="FILTER-IE-EXPLOITS">filter{ie-exploits}</link> \
+ -<link linkend="HANDLE-AS-IMAGE">handle-as-image</link> \
+ +<link linkend="HIDE-FORWARDED-FOR-HEADERS">hide-forwarded-for-headers</link> \
+ +<link linkend="HIDE-FROM-HEADER">hide-from-header{block}</link> \
+ +<link linkend="HIDE-REFERER">hide-referrer{forge}</link> \
+ -<link linkend="HIDE-USER-AGENT">hide-user-agent</link> \
+ -<link linkend="KILL-POPUPS">kill-popups</link> \
+ -<link linkend="LIMIT-CONNECT">limit-connect</link> \
+ +<link linkend="PREVENT-COMPRESSION">prevent-compression</link> \
+ -<link linkend="SEND-VANILLA-WAFER">send-vanilla-wafer</link> \
+ -<link linkend="SEND-WAFER">send-wafer</link> \
+ +<link linkend="SESSION-COOKIES-ONLY">session-cookies-only</link> \
+ +<link linkend="SET-IMAGE-BLOCKER">set-image-blocker{pattern}</link> \
+ }
+ / # forward slash will match *all* potential URL patterns.</screen>
+</para>
+
+<para>
+ The default behavior is now set. Note that some actions, like not hiding
+ the user agent, are part of a <quote>general policy</quote> that applies
+ universally and won't get any exceptions defined later. Other choices,
+ like not blocking (which is <emphasis>understandably</emphasis> the
+ default!) need exceptions, i.e. we need to specify explicitly what we
+ want to block in later sections.
+</para>
+
+<para>
+ The first of our specialized sections is concerned with <quote>fragile</quote>
+ sites, i.e. sites that require minimum interference, because they are either
+ very complex or very keen on tracking you (and have mechanisms in place that
+ make them unusable for people who avoid being tracked). We will simply use
+ our pre-defined <literal>fragile</literal> alias instead of stating the list
+ of actions explicitly:
+</para>
+
+<para>
+ <screen>
+##########################################################################
+# Exceptions for sites that'll break under the default action set:
+##########################################################################
+
+# "Fragile" Use a minimum set of actions for these sites (see alias above):
+#
+{ fragile }
+.office.microsoft.com # surprise, surprise!
+.windowsupdate.microsoft.com</screen>
+</para>
+
+<para>
+ Shopping sites are not as fragile, but they typically
+ require cookies to log in, and pop-up windows for shopping
+ carts or item details. Again, we'll use a pre-defined alias:
+</para>