doc/webserver/user-manual/filter-file.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <HTML
   3 ><HEAD
   4 ><TITLE
   5 >The Filter File</TITLE
   6 ><META
   7 NAME="GENERATOR"
   8 CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
   9 REL="HOME"
  10 TITLE="Privoxy 3.0.3 User Manual"
  11 HREF="index.html"><LINK
  12 REL="PREVIOUS"
  13 TITLE="Actions Files"
  14 HREF="actions-file.html"><LINK
  15 REL="NEXT"
  16 TITLE="Templates"
  17 HREF="templates.html"><LINK
  18 REL="STYLESHEET"
  19 TYPE="text/css"
  20 HREF="../p_doc.css"></HEAD
  21 ><BODY
  22 CLASS="SECT1"
  23 BGCOLOR="#EEEEEE"
  24 TEXT="#000000"
  25 LINK="#0000FF"
  26 VLINK="#840084"
  27 ALINK="#0000FF"
  28 ><DIV
  29 CLASS="NAVHEADER"
  30 ><TABLE
  31 SUMMARY="Header navigation table"
  32 WIDTH="100%"
  33 BORDER="0"
  34 CELLPADDING="0"
  35 CELLSPACING="0"
  36 ><TR
  37 ><TH
  38 COLSPAN="3"
  39 ALIGN="center"
  40 >Privoxy 3.0.3 User Manual</TH
  41 ></TR
  42 ><TR
  43 ><TD
  44 WIDTH="10%"
  45 ALIGN="left"
  46 VALIGN="bottom"
  47 ><A
  48 HREF="actions-file.html"
  49 ACCESSKEY="P"
  50 >Prev</A
  51 ></TD
  52 ><TD
  53 WIDTH="80%"
  54 ALIGN="center"
  55 VALIGN="bottom"
  56 ></TD
  57 ><TD
  58 WIDTH="10%"
  59 ALIGN="right"
  60 VALIGN="bottom"
  61 ><A
  62 HREF="templates.html"
  63 ACCESSKEY="N"
  64 >Next</A
  65 ></TD
  66 ></TR
  67 ></TABLE
  68 ><HR
  69 ALIGN="LEFT"
  70 WIDTH="100%"></DIV
  71 ><DIV
  72 CLASS="SECT1"
  73 ><H1
  74 CLASS="SECT1"
  75 ><A
  76 NAME="FILTER-FILE"
  77 >9. The Filter File</A
  78 ></H1
  79 ><P
  80 > All text substitutions that can be invoked through the
  81  <VAR
  82 CLASS="LITERAL"
  83 ><A
  84 HREF="actions-file.html#FILTER"
  85 >filter</A
  86 ></VAR
  87 > action
  88  must first be defined in the filter file, which is typically
  89  called <TT
  90 CLASS="FILENAME"
  91 >default.filter</TT
  92 > and which can be
  93  selected through the <VAR
  94 CLASS="LITERAL"
  95 > <A
  96 HREF="config.html#FILTERFILE"
  97 >filterfile</A
  98 ></VAR
  99 > config
 100  option.</P
 101 ><P
 102 > Typical reasons for doing such substitutions are to eliminate
 103  common annoyances in HTML and JavaScript, such as pop-up windows,
 104  exit consoles, crippled windows without navigation tools, the
 105  infamous &#60;BLINK&#62; tag etc, to suppress images with certain
 106  width and height attributes (standard banner sizes or web-bugs),
 107  or just to have fun. The possibilities are endless.</P
 108 ><P
 109 > Filtering works on any text-based document type, including
 110  HTML, JavaScript, CSS etc. (all <VAR
 111 CLASS="LITERAL"
 112 >text/*</VAR
 113 >
 114  MIME types, <SPAN
 115 CLASS="emphasis"
 116 ><I
 117 CLASS="EMPHASIS"
 118 >except</I
 119 ></SPAN
 120 > <VAR
 121 CLASS="LITERAL"
 122 >text/plain</VAR
 123 >).
 124  Substitutions are made at the source level, so if you want to <SPAN
 125 CLASS="QUOTE"
 126 >"roll
 127  your own"</SPAN
 128 > filters, you should be familiar with HTML syntax.</P
 129 ><P
 130 > Just like the <A
 131 HREF="actions-file.html"
 132 >actions files</A
 133 >, the
 134  filter file is organized in sections, which are called <SPAN
 135 CLASS="emphasis"
 136 ><I
 137 CLASS="EMPHASIS"
 138 >filters</I
 139 ></SPAN
 140 >
 141  here. Each filter consists of a heading line, that starts with the
 142  <SPAN
 143 CLASS="emphasis"
 144 ><I
 145 CLASS="EMPHASIS"
 146 >keyword</I
 147 ></SPAN
 148 > <VAR
 149 CLASS="LITERAL"
 150 >FILTER:</VAR
 151 >, followed by
 152  the filter's <SPAN
 153 CLASS="emphasis"
 154 ><I
 155 CLASS="EMPHASIS"
 156 >name</I
 157 ></SPAN
 158 >, and a short (one line)
 159  <SPAN
 160 CLASS="emphasis"
 161 ><I
 162 CLASS="EMPHASIS"
 163 >description</I
 164 ></SPAN
 165 > of what it does. Below that line
 166  come the <SPAN
 167 CLASS="emphasis"
 168 ><I
 169 CLASS="EMPHASIS"
 170 >jobs</I
 171 ></SPAN
 172 >, i.e. lines that define the actual
 173  text substitutions. By convention, the name of a filter
 174  should describe what the filter <SPAN
 175 CLASS="emphasis"
 176 ><I
 177 CLASS="EMPHASIS"
 178 >eliminates</I
 179 ></SPAN
 180 >. The
 181  comment is used in the <A
 182 HREF="http://config.privoxy.org/"
 183 TARGET="_top"
 184 >web-based
 185  user interface</A
 186 >.</P
 187 ><P
 188 > Once a filter called <VAR
 189 CLASS="REPLACEABLE"
 190 >name</VAR
 191 > has been defined
 192  in the filter file, it can be invoked by using an action of the form
 193  +<VAR
 194 CLASS="LITERAL"
 195 ><A
 196 HREF="actions-file.html#FILTER"
 197 >filter</A
 198 >{<VAR
 199 CLASS="REPLACEABLE"
 200 >name</VAR
 201 >}</VAR
 202 >
 203  in any <A
 204 HREF="actions-file.html"
 205 >actions file</A
 206 >.</P
 207 ><P
 208 > A filter header line for a filter called <SPAN
 209 CLASS="QUOTE"
 210 >"foo"</SPAN
 211 > could look
 212  like this:</P
 213 ><P
 214 > <TABLE
 215 BORDER="0"
 216 BGCOLOR="#E0E0E0"
 217 WIDTH="100%"
 218 ><TR
 219 ><TD
 220 ><PRE
 221 CLASS="SCREEN"
 222 >FILTER: foo Replace all "foo" with "bar"</PRE
 223 ></TD
 224 ></TR
 225 ></TABLE
 226 ></P
 227 ><P
 228 > Below that line, and up to the next header line, come the jobs that
 229  define what text replacements the filter executes. They are specified
 230  in a syntax that imitates <A
 231 HREF="http://www.perl.org/"
 232 TARGET="_top"
 233 >Perl</A
 234 >'s
 235  <VAR
 236 CLASS="LITERAL"
 237 >s///</VAR
 238 > operator. If you are familiar with Perl, you
 239  will find this to be quite intuitive, and may want to look at the
 240  <A
 241 HREF="http://www.oesterhelt.org/pcrs/pcrs.3.html"
 242 TARGET="_top"
 243 >PCRS man page</A
 244 >
 245  for the subtle differences to Perl behaviour. Most notably, the non-standard
 246  option letter <VAR
 247 CLASS="LITERAL"
 248 >U</VAR
 249 > is supported, which turns the default
 250  to ungreedy matching.</P
 251 ><P
 252 > If you are new to regular expressions, you might want to take a look at
 253  the <A
 254 HREF="appendix.html#REGEX"
 255 >Appendix on regular expressions</A
 256 >, and
 257  see the <A
 258 HREF="http://perldoc.com/perl5.6.1/pod/perl.html"
 259 TARGET="_top"
 260 >Perl
 261  manual</A
 262 > for
 263  <A
 264 HREF="http://perldoc.com/perl5.6.1/pod/perlop.html#s-PATTERN-REPLACEMENT-egimosx"
 265 TARGET="_top"
 266 >the
 267  <VAR
 268 CLASS="LITERAL"
 269 >s///</VAR
 270 > operator's syntax</A
 271 > and <A
 272 HREF="http://perldoc.com/perl5.6.1/pod/perlre.html"
 273 TARGET="_top"
 274 >Perl-style regular
 275  expressions</A
 276 > in general.
 277  The below examples might also help to get you started.</P
 278 ><DIV
 279 CLASS="SECT2"
 280 ><H2
 281 CLASS="SECT2"
 282 ><A
 283 NAME="AEN3212"
 284 >9.1. Filter File Tutorial</A
 285 ></H2
 286 ><P
 287 > Now, let's complete our <SPAN
 288 CLASS="QUOTE"
 289 >"foo"</SPAN
 290 > filter. We have already defined
 291  the heading, but the jobs are still missing. Since all it does is to replace
 292  <SPAN
 293 CLASS="QUOTE"
 294 >"foo"</SPAN
 295 > with <SPAN
 296 CLASS="QUOTE"
 297 >"bar"</SPAN
 298 >, there is only one (trivial) job
 299  needed:</P
 300 ><P
 301 > <TABLE
 302 BORDER="0"
 303 BGCOLOR="#E0E0E0"
 304 WIDTH="100%"
 305 ><TR
 306 ><TD
 307 ><PRE
 308 CLASS="SCREEN"
 309 >s/foo/bar/</PRE
 310 ></TD
 311 ></TR
 312 ></TABLE
 313 ></P
 314 ><P
 315 > But wait! Didn't the comment say that <SPAN
 316 CLASS="emphasis"
 317 ><I
 318 CLASS="EMPHASIS"
 319 >all</I
 320 ></SPAN
 321 > occurrences
 322  of <SPAN
 323 CLASS="QUOTE"
 324 >"foo"</SPAN
 325 > should be replaced? Our current job will only take
 326  care of the first <SPAN
 327 CLASS="QUOTE"
 328 >"foo"</SPAN
 329 > on each page. For global substitution,
 330  we'll need to add the <VAR
 331 CLASS="LITERAL"
 332 >g</VAR
 333 > option:</P
 334 ><P
 335 > <TABLE
 336 BORDER="0"
 337 BGCOLOR="#E0E0E0"
 338 WIDTH="100%"
 339 ><TR
 340 ><TD
 341 ><PRE
 342 CLASS="SCREEN"
 343 >s/foo/bar/g</PRE
 344 ></TD
 345 ></TR
 346 ></TABLE
 347 ></P
 348 ><P
 349 > Our complete filter now looks like this:</P
 350 ><P
 351 > <TABLE
 352 BORDER="0"
 353 BGCOLOR="#E0E0E0"
 354 WIDTH="100%"
 355 ><TR
 356 ><TD
 357 ><PRE
 358 CLASS="SCREEN"
 359 >FILTER: foo Replace all "foo" with "bar"
 360 s/foo/bar/g</PRE
 361 ></TD
 362 ></TR
 363 ></TABLE
 364 ></P
 365 ><P
 366 > Let's look at some real filters for more interesting examples. Here you see
 367  a filter that protects against some common annoyances that arise from JavaScript
 368  abuse. Let's look at its jobs one after the other:</P
 369 ><P
 370 > <TABLE
 371 BORDER="0"
 372 BGCOLOR="#E0E0E0"
 373 WIDTH="100%"
 374 ><TR
 375 ><TD
 376 ><PRE
 377 CLASS="SCREEN"
 378 >FILTER: js-annoyances Get rid of particularly annoying JavaScript abuse
 379
 380 # Get rid of JavaScript referrer tracking. Test page: http://www.randomoddness.com/untitled.htm
 381 #
 382 s|(&#60;script.*)document\.referrer(.*&#60;/script&#62;)|$1"Not Your Business!"$2|Usg</PRE
 383 ></TD
 384 ></TR
 385 ></TABLE
 386 ></P
 387 ><P
 388 > Following the header line and a comment, you see the job. Note that it uses
 389  <VAR
 390 CLASS="LITERAL"
 391 >|</VAR
 392 > as the delimiter instead of <VAR
 393 CLASS="LITERAL"
 394 >/</VAR
 395 >, because
 396  the pattern contains a forward slash, which would otherwise have to be escaped
 397  by a backslash (<VAR
 398 CLASS="LITERAL"
 399 >\</VAR
 400 >).</P
 401 ><P
 402 > Now, let's examine the pattern: it starts with the text <VAR
 403 CLASS="LITERAL"
 404 >&#60;script.*</VAR
 405 >
 406  enclosed in parentheses. Since the dot matches any character, and <VAR
 407 CLASS="LITERAL"
 408 >*</VAR
 409 >
 410  means: <SPAN
 411 CLASS="QUOTE"
 412 >"Match an arbitrary number of the element left of myself"</SPAN
 413 >, this
 414  matches <SPAN
 415 CLASS="QUOTE"
 416 >"&#60;script"</SPAN
 417 >, followed by <SPAN
 418 CLASS="emphasis"
 419 ><I
 420 CLASS="EMPHASIS"
 421 >any</I
 422 ></SPAN
 423 > text, i.e.
 424  it matches the whole page, from the start of the first &#60;script&#62; tag.</P
 425 ><P
 426 > That's more than we want, but the pattern continues: <VAR
 427 CLASS="LITERAL"
 428 >document\.referrer</VAR
 429 >
 430  matches only the exact string <SPAN
 431 CLASS="QUOTE"
 432 >"document.referrer"</SPAN
 433 >. The dot needed to
 434  be <SPAN
 435 CLASS="emphasis"
 436 ><I
 437 CLASS="EMPHASIS"
 438 >escaped</I
 439 ></SPAN
 440 >, i.e. preceded by a backslash, to take away its
 441  special meaning as a joker, and make it just a regular dot. So far, the meaning is:
 442  Match from the start of the first &#60;script&#62; tag in a the page, up to, and including,
 443  the text <SPAN
 444 CLASS="QUOTE"
 445 >"document.referrer"</SPAN
 446 >, if <SPAN
 447 CLASS="emphasis"
 448 ><I
 449 CLASS="EMPHASIS"
 450 >both</I
 451 ></SPAN
 452 > are present
 453  in the page (and appear in that order).</P
 454 ><P
 455 > But there's still more pattern to go. The next element, again enclosed in parentheses,
 456  is <VAR
 457 CLASS="LITERAL"
 458 >.*&#60;/script&#62;</VAR
 459 >. You already know what <VAR
 460 CLASS="LITERAL"
 461 >.*</VAR
 462 >
 463  means, so the whole pattern translates to: Match from the start of the first  &#60;script&#62;
 464  tag in a page to the end of the last &#60;script&#62; tag, provided that the text
 465  <SPAN
 466 CLASS="QUOTE"
 467 >"document.referrer"</SPAN
 468 > appears somewhere in between.</P
 469 ><P
 470 > This is still not the whole story, since we have ignored the options and the parentheses:
 471  The portions of the page matched by sub-patterns that are enclosed in parentheses, will be
 472  remembered and be available through the variables <VAR
 473 CLASS="LITERAL"
 474 >$1, $2, ...</VAR
 475 > in
 476  the substitute. The <VAR
 477 CLASS="LITERAL"
 478 >U</VAR
 479 > option switches to ungreedy matching, which means
 480  that the first <VAR
 481 CLASS="LITERAL"
 482 >.*</VAR
 483 > in the pattern will only <SPAN
 484 CLASS="QUOTE"
 485 >"eat up"</SPAN
 486 > all
 487  text in between <SPAN
 488 CLASS="QUOTE"
 489 >"&#60;script"</SPAN
 490 > and the <SPAN
 491 CLASS="emphasis"
 492 ><I
 493 CLASS="EMPHASIS"
 494 >first</I
 495 ></SPAN
 496 > occurrence
 497  of <SPAN
 498 CLASS="QUOTE"
 499 >"document.referrer"</SPAN
 500 >, and that the second <VAR
 501 CLASS="LITERAL"
 502 >.*</VAR
 503 > will
 504  only span the text up to the <SPAN
 505 CLASS="emphasis"
 506 ><I
 507 CLASS="EMPHASIS"
 508 >first</I
 509 ></SPAN
 510 > <SPAN
 511 CLASS="QUOTE"
 512 >"&#60;/script&#62;"</SPAN
 513 >
 514  tag. Furthermore, the <VAR
 515 CLASS="LITERAL"
 516 >s</VAR
 517 > option says that the match may span
 518  multiple lines in the page, and the <VAR
 519 CLASS="LITERAL"
 520 >g</VAR
 521 > option again means that the
 522  substitution is global.</P
 523 ><P
 524 > So, to summarize, the pattern means: Match all scripts that contain the text
 525  <SPAN
 526 CLASS="QUOTE"
 527 >"document.referrer"</SPAN
 528 >. Remember the parts of the script from
 529  (and including) the start tag up to (and excluding) the string
 530  <SPAN
 531 CLASS="QUOTE"
 532 >"document.referrer"</SPAN
 533 > as <VAR
 534 CLASS="LITERAL"
 535 >$1</VAR
 536 >, and the part following
 537  that string, up to and including the closing tag, as <VAR
 538 CLASS="LITERAL"
 539 >$2</VAR
 540 >.</P
 541 ><P
 542 > Now the pattern is deciphered, but wasn't this about substituting things? So
 543  lets look at the substitute: <VAR
 544 CLASS="LITERAL"
 545 >$1"Not Your Business!"$2</VAR
 546 > is
 547  easy to read: The text remembered as <VAR
 548 CLASS="LITERAL"
 549 >$1</VAR
 550 >, followed by
 551  <VAR
 552 CLASS="LITERAL"
 553 >"Not Your Business!"</VAR
 554 > (<SPAN
 555 CLASS="emphasis"
 556 ><I
 557 CLASS="EMPHASIS"
 558 >including</I
 559 ></SPAN
 560 >
 561  the quotation marks!), followed by the text remembered as <VAR
 562 CLASS="LITERAL"
 563 >$2</VAR
 564 >.
 565  This produces an exact copy of the original string, with the middle part
 566  (the <SPAN
 567 CLASS="QUOTE"
 568 >"document.referrer"</SPAN
 569 >) replaced by <VAR
 570 CLASS="LITERAL"
 571 >"Not Your
 572  Business!"</VAR
 573 >.</P
 574 ><P
 575 > The whole job now reads: Replace <SPAN
 576 CLASS="QUOTE"
 577 >"document.referrer"</SPAN
 578 > by
 579  <VAR
 580 CLASS="LITERAL"
 581 >"Not Your Business!"</VAR
 582 > wherever it appears inside a
 583  &#60;script&#62; tag. Note that this job won't break JavaScript syntax,
 584  since both the original and the replacement are syntactically valid
 585  string objects. The script just won't have access to the referrer
 586  information anymore.</P
 587 ><P
 588 > We'll show you two other jobs from the JavaScript taming department, but
 589  this time only point out the constructs of special interest:</P
 590 ><P
 591 > <TABLE
 592 BORDER="0"
 593 BGCOLOR="#E0E0E0"
 594 WIDTH="100%"
 595 ><TR
 596 ><TD
 597 ><PRE
 598 CLASS="SCREEN"
 599 ># The status bar is for displaying link targets, not pointless blahblah
 600 #
 601 s/window\.status\s*=\s*(['"]).*?\1/dUmMy=1/ig</PRE
 602 ></TD
 603 ></TR
 604 ></TABLE
 605 ></P
 606 ><P
 607 > <VAR
 608 CLASS="LITERAL"
 609 >\s</VAR
 610 > stands for whitespace characters (space, tab, newline,
 611  carriage return, form feed), so that <VAR
 612 CLASS="LITERAL"
 613 >\s*</VAR
 614 > means: <SPAN
 615 CLASS="QUOTE"
 616 >"zero
 617  or more whitespace"</SPAN
 618 >. The <VAR
 619 CLASS="LITERAL"
 620 >?</VAR
 621 > in <VAR
 622 CLASS="LITERAL"
 623 >.*?</VAR
 624 >
 625  makes this matching of arbitrary text ungreedy. (Note that the <VAR
 626 CLASS="LITERAL"
 627 >U</VAR
 628 >
 629  option is not set). The <VAR
 630 CLASS="LITERAL"
 631 >['"]</VAR
 632 > construct means: <SPAN
 633 CLASS="QUOTE"
 634 >"a single
 635  <SPAN
 636 CLASS="emphasis"
 637 ><I
 638 CLASS="EMPHASIS"
 639 >or</I
 640 ></SPAN
 641 > a double quote"</SPAN
 642 >. Finally, <VAR
 643 CLASS="LITERAL"
 644 >\1</VAR
 645 > is
 646  a backreference to the first parenthesis just like <VAR
 647 CLASS="LITERAL"
 648 >$1</VAR
 649 > above,
 650  with the difference that in the <SPAN
 651 CLASS="emphasis"
 652 ><I
 653 CLASS="EMPHASIS"
 654 >pattern</I
 655 ></SPAN
 656 >, a backslash indicates
 657  a backreference, whereas in the <SPAN
 658 CLASS="emphasis"
 659 ><I
 660 CLASS="EMPHASIS"
 661 >substitute</I
 662 ></SPAN
 663 >, it's the dollar.</P
 664 ><P
 665 > So what does this job do? It replaces assignments of single- or double-quoted
 666  strings to the <SPAN
 667 CLASS="QUOTE"
 668 >"window.status"</SPAN
 669 > object with a dummy assignment
 670  (using a variable name that is hopefully odd enough not to conflict with
 671  real variables in scripts). Thus, it catches many cases where e.g. pointless
 672  descriptions are displayed in the status bar instead of the link target when
 673  you move your mouse over links.</P
 674 ><P
 675 > <TABLE
 676 BORDER="0"
 677 BGCOLOR="#E0E0E0"
 678 WIDTH="100%"
 679 ><TR
 680 ><TD
 681 ><PRE
 682 CLASS="SCREEN"
 683 ># Kill OnUnload popups. Yummy. Test: http://www.zdnet.com/zdsubs/yahoo/tree/yfs.html
 684 #
 685 s/(&#60;body [^&#62;]*)onunload(.*&#62;)/$1never$2/iU</PRE
 686 ></TD
 687 ></TR
 688 ></TABLE
 689 ></P
 690 ><P
 691 > Including the
 692  <A
 693 HREF="http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/events.html#Events-eventgroupings-htmlevents"
 694 TARGET="_top"
 695 >OnUnload
 696  event binding</A
 697 > in the HTML DOM was a <SPAN
 698 CLASS="emphasis"
 699 ><I
 700 CLASS="EMPHASIS"
 701 >CRIME</I
 702 ></SPAN
 703 >.
 704  When I close a browser window, I want it to close and die. Basta.
 705  This job replaces the <SPAN
 706 CLASS="QUOTE"
 707 >"onunload"</SPAN
 708 > attribute in
 709  <SPAN
 710 CLASS="QUOTE"
 711 >"&#60;body&#62;"</SPAN
 712 > tags with the dummy word <VAR
 713 CLASS="LITERAL"
 714 >never</VAR
 715 >.
 716  Note that the <VAR
 717 CLASS="LITERAL"
 718 >i</VAR
 719 > option makes the pattern matching
 720  case-insensitive. Also note that ungreedy matching alone doesn't always guarantee
 721  a minimal match: In the first parenthesis, we had to use <VAR
 722 CLASS="LITERAL"
 723 >[^&#62;]*</VAR
 724 >
 725  instead of <VAR
 726 CLASS="LITERAL"
 727 >.*</VAR
 728 > to prevent the match from exceeding the
 729  &#60;body&#62; tag if it doesn't contain <SPAN
 730 CLASS="QUOTE"
 731 >"OnUnload"</SPAN
 732 >, but the page's
 733  content does.</P
 734 ><P
 735 > The last example is from the fun department:</P
 736 ><P
 737 > <TABLE
 738 BORDER="0"
 739 BGCOLOR="#E0E0E0"
 740 WIDTH="100%"
 741 ><TR
 742 ><TD
 743 ><PRE
 744 CLASS="SCREEN"
 745 >FILTER: fun Fun text replacements
 746
 747 # Spice the daily news:
 748 #
 749 s/microsoft(?!\.com)/MicroSuck/ig</PRE
 750 ></TD
 751 ></TR
 752 ></TABLE
 753 ></P
 754 ><P
 755 > Note the <VAR
 756 CLASS="LITERAL"
 757 >(?!\.com)</VAR
 758 > part (a so-called negative lookahead)
 759  in the job's pattern, which means: Don't match, if the string
 760  <SPAN
 761 CLASS="QUOTE"
 762 >".com"</SPAN
 763 > appears directly following <SPAN
 764 CLASS="QUOTE"
 765 >"microsoft"</SPAN
 766 >
 767  in the page. This prevents links to microsoft.com from being trashed, while
 768  still replacing the word everywhere else.</P
 769 ><P
 770 > <TABLE
 771 BORDER="0"
 772 BGCOLOR="#E0E0E0"
 773 WIDTH="100%"
 774 ><TR
 775 ><TD
 776 ><PRE
 777 CLASS="SCREEN"
 778 ># Buzzword Bingo (example for extended regex syntax)
 779 #
 780 s* industry[ -]leading \
 781 |  cutting[ -]edge \
 782 |  customer[ -]focused \
 783 |  market[ -]driven \
 784 |  award[ -]winning # Comments are OK, too! \
 785 |  high[ -]performance \
 786 |  solutions[ -]based \
 787 |  unmatched \
 788 |  unparalleled \
 789 |  unrivalled \
 790 *&#60;font color="red"&#62;&#60;b&#62;BINGO!&#60;/b&#62;&#60;/font&#62; \
 791 *igx</PRE
 792 ></TD
 793 ></TR
 794 ></TABLE
 795 ></P
 796 ><P
 797 > The <VAR
 798 CLASS="LITERAL"
 799 >x</VAR
 800 > option in this job turns on extended syntax, and allows for
 801  e.g. the liberal use of (non-interpreted!) whitespace for nicer formatting. </P
 802 ><P
 803 > You get the idea?</P
 804 ></DIV
 805 ><DIV
 806 CLASS="SECT2"
 807 ><H2
 808 CLASS="SECT2"
 809 ><A
 810 NAME="PREDEFINED-FILTERS"
 811 >9.2. The Pre-defined Filters</A
 812 ></H2
 813 ><P
 814 >The distribution <TT
 815 CLASS="FILENAME"
 816 >default.filter</TT
 817 > file contains a selection of
 818 pre-defined filters for your convenience:</P
 819 ><P
 820 ></P
 821 ><DIV
 822 CLASS="VARIABLELIST"
 823 ><DL
 824 ><DT
 825 ><SPAN
 826 CLASS="emphasis"
 827 ><I
 828 CLASS="EMPHASIS"
 829 >js-annoyances</I
 830 ></SPAN
 831 ></DT
 832 ><DD
 833 ><P
 834 >    The purpose of this filter is to get rid of particularly annoying JavaScript abuse.
 835     To that end, it
 836    <P
 837 ></P
 838 ><UL
 839 ><LI
 840 ><P
 841 >      replaces JavaScript references to the browser's referrer information
 842       with the string "Not Your Business!". This compliments the <VAR
 843 CLASS="LITERAL"
 844 ><A
 845 HREF="actions-file.html#HIDE-REFERRER"
 846 >hide-referrer</A
 847 ></VAR
 848 > action on the content level.
 849      </P
 850 ></LI
 851 ><LI
 852 ><P
 853 >      removes the bindings to the DOM's
 854       <A
 855 HREF="http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/events.html#Events-eventgroupings-htmlevents"
 856 TARGET="_top"
 857 >unload
 858       event</A
 859 > which we feel has no right to exist and is responsible for most <SPAN
 860 CLASS="QUOTE"
 861 >"exit consoles"</SPAN
 862 >, i.e.
 863       nasty windows that pop up when you close another one.
 864      </P
 865 ></LI
 866 ><LI
 867 ><P
 868 >      removes code that causes new windows to be opened with undesired properties, such as being
 869       full-screen, non-resizable, without location, status or menu bar etc.
 870      </P
 871 ></LI
 872 ></UL
 873 >
 874    </P
 875 ></DD
 876 ><DT
 877 ><SPAN
 878 CLASS="emphasis"
 879 ><I
 880 CLASS="EMPHASIS"
 881 >js-events</I
 882 ></SPAN
 883 ></DT
 884 ><DD
 885 ><P
 886 >    This is a very radical measure. It removes virtually all JavaScript event bindings, which
 887     means that scripts can not react to user actions such as mouse movements or clicks, window
 888     resizing etc, anymore.
 889    </P
 890 ><P
 891 >    We <SPAN
 892 CLASS="emphasis"
 893 ><I
 894 CLASS="EMPHASIS"
 895 >strongly discourage</I
 896 ></SPAN
 897 > using this filter as a default since it breaks
 898     many legitimate scripts. It is meant for use only on extra-nasty sites (should you really
 899     need to go there).
 900    </P
 901 ></DD
 902 ><DT
 903 ><SPAN
 904 CLASS="emphasis"
 905 ><I
 906 CLASS="EMPHASIS"
 907 >html-annoyances</I
 908 ></SPAN
 909 ></DT
 910 ><DD
 911 ><P
 912 >    This filter will undo many common instances of HTML based abuse.
 913    </P
 914 ><P
 915 >    The <VAR
 916 CLASS="LITERAL"
 917 >BLINK</VAR
 918 > and <VAR
 919 CLASS="LITERAL"
 920 >MARQUEE</VAR
 921 > tags
 922     are neutralized (yeah baby!), and browser windows will be created as
 923     resizable (as of course they should be!), and will have location,
 924     scroll and menu bars -- even if specified otherwise.
 925    </P
 926 ></DD
 927 ><DT
 928 ><SPAN
 929 CLASS="emphasis"
 930 ><I
 931 CLASS="EMPHASIS"
 932 >content-cookies</I
 933 ></SPAN
 934 ></DT
 935 ><DD
 936 ><P
 937 >    Most cookies are set in the HTTP dialogue, where they can be intercepted
 938     by the
 939     <VAR
 940 CLASS="LITERAL"
 941 ><A
 942 HREF="actions-file.html#CRUNCH-INCOMING-COOKIES"
 943 >crunch-incoming-cookies</A
 944 ></VAR
 945 >
 946     and <VAR
 947 CLASS="LITERAL"
 948 ><A
 949 HREF="actions-file.html#CRUNCH-OUTGOING-COOKIES"
 950 >crunch-outgoing-cookies</A
 951 ></VAR
 952 >
 953     actions. But web sites increasingly make use of HTML meta tags and JavaScript
 954     to sneak cookies to the browser on the content level.
 955    </P
 956 ><P
 957 >    This filter disables HTML and JavaScript code that reads or sets cookies. Use
 958     it wherever you would also use the cookie crunch actions.
 959    </P
 960 ></DD
 961 ><DT
 962 ><SPAN
 963 CLASS="emphasis"
 964 ><I
 965 CLASS="EMPHASIS"
 966 >refresh tags</I
 967 ></SPAN
 968 ></DT
 969 ><DD
 970 ><P
 971 >    Disable any refresh tags if the interval is greater than nine seconds (so
 972     that redirections done via refresh tags are not destroyed). This is useful
 973     for dial-on-demand setups, or for those who find this HTML feature
 974     annoying.
 975    </P
 976 ></DD
 977 ><DT
 978 ><SPAN
 979 CLASS="emphasis"
 980 ><I
 981 CLASS="EMPHASIS"
 982 >unsolicited-popups</I
 983 ></SPAN
 984 ></DT
 985 ><DD
 986 ><P
 987 >    This filter attempts to prevent only <SPAN
 988 CLASS="QUOTE"
 989 >"unsolicited"</SPAN
 990 > pop-up
 991     windows from opening, yet still allow pop-up windows that the user
 992     has explicitly chosen to open. It was added in version 3.0.1,
 993     as an improvement over earlier such filters.
 994    </P
 995 ><P
 996 >    Technical note: The filter works by redefining the window.open JavaScript
 997     function to a dummy function during the loading and rendering phase of each
 998     HTML page access, and restoring the function afterwards.
 999    </P
1000 ></DD
1001 ><DT
1002 ><SPAN
1003 CLASS="emphasis"
1004 ><I
1005 CLASS="EMPHASIS"
1006 >all-popups</I
1007 ></SPAN
1008 ></DT
1009 ><DD
1010 ><P
1011 >    Attempt to prevent <SPAN
1012 CLASS="emphasis"
1013 ><I
1014 CLASS="EMPHASIS"
1015 >all</I
1016 ></SPAN
1017 > pop-up windows from opening.
1018     Note this should be used with more discretion than the above, since it is
1019     more likely to break some sites that require pop-ups for normal usage. Use
1020     with caution.
1021    </P
1022 ></DD
1023 ><DT
1024 ><SPAN
1025 CLASS="emphasis"
1026 ><I
1027 CLASS="EMPHASIS"
1028 >img-reorder</I
1029 ></SPAN
1030 ></DT
1031 ><DD
1032 ><P
1033 >    This is a helper filter that has no value if used alone. It makes the
1034     <VAR
1035 CLASS="LITERAL"
1036 >banners-by-size</VAR
1037 > and <VAR
1038 CLASS="LITERAL"
1039 >banners-by-link</VAR
1040 >
1041     (see below) filters more effective and should be enabled together with them.
1042    </P
1043 ></DD
1044 ><DT
1045 ><SPAN
1046 CLASS="emphasis"
1047 ><I
1048 CLASS="EMPHASIS"
1049 >banners-by-size</I
1050 ></SPAN
1051 ></DT
1052 ><DD
1053 ><P
1054 >    This filter removes image tags purely based on what size they are. Fortunately
1055     for us, many ads and banner images tend to conform to certain standardized
1056     sizes, which makes this filter quite effective for ad stripping purposes.
1057    </P
1058 ><P
1059 >    Occasionally this filter will cause false positives on images that are not ads,
1060     but just happen to be of one of the standard banner sizes.
1061    </P
1062 ></DD
1063 ><DT
1064 ><SPAN
1065 CLASS="emphasis"
1066 ><I
1067 CLASS="EMPHASIS"
1068 >banners-by-link</I
1069 ></SPAN
1070 ></DT
1071 ><DD
1072 ><P
1073 >    This is an experimental filter that attempts to kill any banners if
1074     their URLs seem to point to known or suspected click trackers. It is currently
1075     not of much value and is not recommended for use by default.
1076    </P
1077 ></DD
1078 ><DT
1079 ><SPAN
1080 CLASS="emphasis"
1081 ><I
1082 CLASS="EMPHASIS"
1083 >webbugs</I
1084 ></SPAN
1085 ></DT
1086 ><DD
1087 ><P
1088 >    Webbugs are small, invisible images (technically 1X1 GIF images), that
1089     are used to track users across websites, and collect information on them.
1090     As an HTML page is loaded by the browser, an embedded image tag causes the
1091     browser to contact a third-party site, disclosing the tracking information
1092     through the requested URL and/or cookies for that third-party domain, without
1093     the use ever becoming aware of the interaction with the third-party site.
1094     HTML-ized spam also uses a similar technique to verify email addresses.
1095    </P
1096 ><P
1097 >    This filter removes the HTML code that loads such <SPAN
1098 CLASS="QUOTE"
1099 >"webbugs"</SPAN
1100 >.
1101    </P
1102 ></DD
1103 ><DT
1104 ><SPAN
1105 CLASS="emphasis"
1106 ><I
1107 CLASS="EMPHASIS"
1108 >tiny-textforms</I
1109 ></SPAN
1110 ></DT
1111 ><DD
1112 ><P
1113 >    A rather special-purpose filter that can be used to enlarge textareas (those
1114     multi-line text boxes in web forms) and turn off hard word wrap in them.
1115     It was written for the sourceforge.net tracker system where such boxes are
1116     a nuisance, but it can be handy on other sites, too.
1117    </P
1118 ><P
1119 >    It is not recommended to use this filter as a default.
1120    </P
1121 ></DD
1122 ><DT
1123 ><SPAN
1124 CLASS="emphasis"
1125 ><I
1126 CLASS="EMPHASIS"
1127 >jumping-windows</I
1128 ></SPAN
1129 ></DT
1130 ><DD
1131 ><P
1132 >    Many consider windows that move, or resize themselves to be abusive. This filter
1133     neutralizes the related JavaScript code. Note that some sites might not display
1134     or behave as intended when using this filter.
1135    </P
1136 ></DD
1137 ><DT
1138 ><SPAN
1139 CLASS="emphasis"
1140 ><I
1141 CLASS="EMPHASIS"
1142 >frameset-borders</I
1143 ></SPAN
1144 ></DT
1145 ><DD
1146 ><P
1147 >    Some web designers seem to assume that everyone in the world will view their
1148     web sites using the same browser brand and version, screen resolution etc,
1149     because only that assumption could explain why they'd use static frame sizes,
1150     yet prevent their frames from being resized by the user, should they be too
1151     small to show their whole content.
1152    </P
1153 ><P
1154 >    This filter removes the related HTML code. It should only be applied to sites
1155     which need it.
1156    </P
1157 ></DD
1158 ><DT
1159 ><SPAN
1160 CLASS="emphasis"
1161 ><I
1162 CLASS="EMPHASIS"
1163 >demoronizer</I
1164 ></SPAN
1165 ></DT
1166 ><DD
1167 ><P
1168 >    Many Microsoft products that generate HTML use non-standard extensions (read:
1169     violations) of the ISO 8859-1 aka Latin-1 character set. This causes those
1170     HTML documents to display with errors on standard-compliant platforms.
1171    </P
1172 ><P
1173 >    This filter translates the MS-only characters into Latin-1 equivalents.
1174     It is not necessary when using MS products, and will cause corruption of
1175     all documents that use 8-bit character sets other than Latin-1. It's mostly
1176     worthwhile for Europeans on non-MS platforms, if wierd garbage characters
1177     sometimes appear on some pages.
1178    </P
1179 ></DD
1180 ><DT
1181 ><SPAN
1182 CLASS="emphasis"
1183 ><I
1184 CLASS="EMPHASIS"
1185 >shockwave-flash</I
1186 ></SPAN
1187 ></DT
1188 ><DD
1189 ><P
1190 >    A filter for shockwave haters. As the name suggests, this filter strips code
1191     out of web pages that is used to embed shockwave flash objects.
1192    </P
1193 ><P
1194 >   </P
1195 ></DD
1196 ><DT
1197 ><SPAN
1198 CLASS="emphasis"
1199 ><I
1200 CLASS="EMPHASIS"
1201 >quicktime-kioskmode</I
1202 ></SPAN
1203 ></DT
1204 ><DD
1205 ><P
1206 >    Change HTML code that embeds Quicktime objects so that kioskmode, which
1207     prevents saving, is disabled.
1208    </P
1209 ></DD
1210 ><DT
1211 ><SPAN
1212 CLASS="emphasis"
1213 ><I
1214 CLASS="EMPHASIS"
1215 >fun</I
1216 ></SPAN
1217 ></DT
1218 ><DD
1219 ><P
1220 >    Text replacements for subversive browsing fun. Make fun of your favorite
1221     Monopolist or play buzzword bingo.
1222    </P
1223 ></DD
1224 ><DT
1225 ><SPAN
1226 CLASS="emphasis"
1227 ><I
1228 CLASS="EMPHASIS"
1229 >crude-parental</I
1230 ></SPAN
1231 ></DT
1232 ><DD
1233 ><P
1234 >    A demonstration-only filter that shows how <SPAN
1235 CLASS="APPLICATION"
1236 >Privoxy</SPAN
1237 >
1238     can be used to delete web content on a keyword basis.
1239    </P
1240 ></DD
1241 ><DT
1242 ><SPAN
1243 CLASS="emphasis"
1244 ><I
1245 CLASS="EMPHASIS"
1246 >ie-exploits</I
1247 ></SPAN
1248 ></DT
1249 ><DD
1250 ><P
1251 >    A collection of text replacements to disable malicious HTML and JavaScript
1252     code that exploits known security holes in Internet Explorer.
1253    </P
1254 ><P
1255 >    Presently, it only protects against Nimda and a cross-site scripting bug, and
1256     would need active maintenance to provide more substantial protection.
1257    </P
1258 ></DD
1259 ><DT
1260 ><SPAN
1261 CLASS="emphasis"
1262 ><I
1263 CLASS="EMPHASIS"
1264 >site-specifics</I
1265 ></SPAN
1266 ></DT
1267 ><DD
1268 ><P
1269 >    Some web sites have very specific problems, the cure for which doesn't apply
1270     anywhere else, or could even cause damage on other sites.
1271    </P
1272 ><P
1273 >    This is a collection of such site-specific cures which should only be applied
1274     to the sites they were intended for, which is what the supplied
1275     <TT
1276 CLASS="FILENAME"
1277 >default.action</TT
1278 > file does. Users shouldn't need to change
1279     anything regarding this filter.
1280    </P
1281 ></DD
1282 ></DL
1283 ></DIV
1284 ></DIV
1285 ></DIV
1286 ><DIV
1287 CLASS="NAVFOOTER"
1288 ><HR
1289 ALIGN="LEFT"
1290 WIDTH="100%"><TABLE
1291 SUMMARY="Footer navigation table"
1292 WIDTH="100%"
1293 BORDER="0"
1294 CELLPADDING="0"
1295 CELLSPACING="0"
1296 ><TR
1297 ><TD
1298 WIDTH="33%"
1299 ALIGN="left"
1300 VALIGN="top"
1301 ><A
1302 HREF="actions-file.html"
1303 ACCESSKEY="P"
1304 >Prev</A
1305 ></TD
1306 ><TD
1307 WIDTH="34%"
1308 ALIGN="center"
1309 VALIGN="top"
1310 ><A
1311 HREF="index.html"
1312 ACCESSKEY="H"
1313 >Home</A
1314 ></TD
1315 ><TD
1316 WIDTH="33%"
1317 ALIGN="right"
1318 VALIGN="top"
1319 ><A
1320 HREF="templates.html"
1321 ACCESSKEY="N"
1322 >Next</A
1323 ></TD
1324 ></TR
1325 ><TR
1326 ><TD
1327 WIDTH="33%"
1328 ALIGN="left"
1329 VALIGN="top"
1330 >Actions Files</TD
1331 ><TD
1332 WIDTH="34%"
1333 ALIGN="center"
1334 VALIGN="top"
1335 >&nbsp;</TD
1336 ><TD
1337 WIDTH="33%"
1338 ALIGN="right"
1339 VALIGN="top"
1340 >Templates</TD
1341 ></TR
1342 ></TABLE
1343 ></DIV
1344 ></BODY
1345 ></HTML
1346 >