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

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