Noissue - Document the new $generichide and $genericblock filter options

pages/filters.html

 title=Writing Adblock Plus filters
 
 
 <p>{{s1 Current Adblock Plus versions allow you to "tweak" your filters in many different ways. This document explains the choices that you have and how they can be used.}}</p>
 
   <p>{{s2 <em>Disclaimer</em>: All filter examples given here are really only examples and are not meant to be used.}}</p>
 
   <h2 id="introduction">{{s3 Introduction to Adblock Plus filters}}</h2>
 
   <p>{{s4 The options described in this section should be enough for users who have to create a filter occasionally.}}</p>
@@ skipping 134 matching lines @@
       <ul>
         <li>{{s57 <code><fix>script</fix></code> — external scripts loaded via HTML script tag}}</li>
         <li>{{s58 <code><fix>image</fix></code> — regular images, typically loaded via HTML img tag}}</li>
         <li>{{s59 <code><fix>stylesheet</fix></code> — external CSS stylesheet files}}</li>
         <li>{{s60 <code><fix>object</fix></code> — content handled by browser plugins, e.g. Flash or Java}}</li>
         <li>{{s62 <code><fix>xmlhttprequest</fix></code> — requests started by the <a href="{{s62-link http://www.w3.org/TR/XMLHttpRequest/}}">XMLHttpRequest object</a>}}</li>
         <li>{{s63 <code><fix>object-subrequest</fix></code> — requests started plugins like Flash}}</li>
         <li>{{s64 <code><fix>subdocument</fix></code> — embedded pages, usually included via HTML frames}}</li>
         <li>{{s65 <code><fix>document</fix></code> — the page itself (only <a href="#whitelist">exception rules</a> can be applied to the page)}}</li>
         <li>{{s66 <code><fix>elemhide</fix></code> — for exception rules only, similar to <code><fix>document</fix></code> but only disables <a href="#elemhide">element hiding rules</a> on the page rather than all filter rules (Adblock Plus 1.2 and higher required)}}</li>
+        <li>{{generichide <code><fix>generichide</fix></code> — for exception rules only, similar to <code><fix>elemhide</fix></code> but only disables <a href="#generic-specific">generic</a> element hiding rules on the page (Adblock Plus 2.6.12 and higher required)}}</li>
+        <li>{{genericblock <code><fix>genericblock</fix></code> — for exception rules only, just like <code><fix>generichide</fix></code> but disables <a href="#generic-specific">generic</a> blocking rules (Adblock Plus 2.6.12 and higher required)}}</li>
         <li>{{s67 <code><fix>other</fix></code> — types of requests not covered in the list above}}</li>
       </ul>
       {{s68 The type options <code><fix>background</fix></code>, <code><fix>xbl</fix></code>,
       <code><fix>ping</fix></code> and <code><fix>dtd</fix></code> are outdated and should no
       longer be used.}}
     </li>
     <li>{{s69 Inverse type options: specify the element types the filter should <strong>not</strong> be applied to. Possible inverse type options: <code><fix>~script</fix></code>, <code><fix>~image</fix></code>, <code><fix>~stylesheet</fix></code>, <code><fix>~object</fix></code>, <code><fix>~xmlhttprequest</fix></code>, <code><fix>~object-subrequest</fix></code>, <code><fix>~subdocument</fix></code>, <code><fix>~document</fix></code>, <code><fix>~elemhide</fix></code>, <code><fix>~other</fix></code>}}</li>
     <li>{{s70 Restriction to third-party/first-party requests: If the <code><fix>third-party</fix></code> option is specified, the filter is only applied to requests from a different origin than the currently viewed page. Similarly, <code><fix>~third-party</fix></code> restricts the filter to requests from the same origin as the currently viewed page.}}</li>
     <li>{{s71 Domain restrictions: The option <code><fix>domain=example.com</fix></code> means that the filter should only be applied on pages from "example.com" domain. Multiple domains can be specified using "|" as separator: with the option <code><fix>domain=example.com|example.net</fix></code> the filter will only be applied on pages from "example.com" or "example.net" domains. If a domain name is preceded with "~", the filter should <strong>not</strong> be applied on pages from this domain. For example, <code><fix>domain=~example.com</fix></code> means that the filter should be applied on pages from any domain but "example.com" and <code><fix>domain=example.com|~foo.example.com</fix></code> restricts the filter to the "example.com" domain with the exception of "foo.example.com" subdomain.}}</li>
     <li>
@@ skipping 74 matching lines @@
   rules has exactly the same effect as the single rule
   <code><fix>~example.com##div.textad</fix></code>.}} {{s104 It is recommended that you use
   exception rules only when you cannot change an overly general element hiding rule, in all the
   other cases limiting this rule to the necessary domains is preferable.}}
 </p>
 
   <h3 id="elemhide_simplified">{{s105 Simplified element hiding syntax}}</h3>
 
   <p>{{s106 Adblock Plus supports simplified element hiding syntax (e.g. <code><fix>#div(id=foo)</fix></code>) for backwards compatibility only. Using this syntax is discouraged, usual CSS selectors are preferred. Support for this syntax might be removed at some point.}}</p>
 
+  <h3 id="generic-specific">{{generic-specific-title Generic / Specific filters}}</h3>
+
+  <p>{{generic-specific-explanation-p1 With the <code><fix>$generichide</fix></code> and <code><fix>$genericblock</fix></code> filter options the distinction between generic and specific filters becomes important.}}</p>
+  <p>{{generic-specific-explanation-p2 We classify a filter to be <strong>specific</strong> if it matches one or more domains or matches a sitekey. If a filter has no domains specified (or only domain exceptions) and no sitekey then it counts as <strong>generic</strong>. For example <code><fix>example.com##div.textad</fix></code> is a specific filter, whereas both <code><fix>##div.textad</fix></code> and <code><fix>~example.com##div.textad</fix></code> are generic.}}</p>

[Wladimir Palant, 2015/11/24 11:15:38]

Nit: comma after "For example"

[kzar, 2015/11/24 11:18:29]

Done.

+  <p>{{generic-specific-explanation-p3 Note that with blocking rules the domain must be specified under the $domain option for them to be considered specific. For example <code><fix>||example.com^</fix></code> is considered generic whereas <code><fix>*/ads/*$domain=example.com</fix></code> is site-specific.}}</p>

[Wladimir Palant, 2015/11/24 11:15:38]

Same here.

[kzar, 2015/11/24 11:18:30]

Done.

+
   <h2 id="sitekey_server">{{s107 Implementing a sitekey on the server}}</h2>
 
 <p>
   {{s108 For a <a href="#options">sitekey-restricted filter</a> to apply, a webpage needs to return base64-encoded versions of the public key and a signature which Adblock Plus can validate. Currently, this means including them in both the HTTP response header (<code><fix>X-Adblock-Key: abcdpublickeydcba_abcdsignaturedcba</fix></code>) and the root tag of the document (<code><fix>&lt;html data-adblockkey="abcdpublickeydcba_abcdsignaturedcba"&gt;</fix></code>).}}
 </p>
 
 <p>
   {{s109 First you need to create a private RSA key (preferably 512 bit to keep the transfer volume low) and then a DER representation of the public key.}}
 </p>
 
 <p>
   {{s110 The data used for creating the signature is a concatenated list of request variables (namely URI, host and user agent) separated by the <code><fix>NUL</fix></code> character "\0". For example:}}
 </p>
 
 <pre>
   /index.html?q=foo\0www.example.com\0Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:30.0) Gecko/20100101 Firefox/30.0
 </pre>
 
 <p>
   {{s111 Finally, generate the signature for this string by using the signature algorithm SEC_OID_ISO_SHA_WITH_RSA_SIGNATURE (default when using OpenSSL).}}
 </p>