Issue 5353 - Add advanced element hiding filters documentation

pages/filters.html

Index: pages/filters.html
===================================================================
--- a/pages/filters.html
+++ b/pages/filters.html
@@ -242,16 +242,34 @@
   disabled on <code><fix>example.com</fix></code> using the exception rule
   <code><fix>example.com#@#div.textad</fix></code>.}} {{s103 The combination of these two
   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-emulation">{{elemhide-emulation-title Advanced element hiding}}</h3>

[kzar, 2017/07/11 12:56:17]

It seems more logical to me to put this new section before the element hiding
exception one.

I wonder if there's a better title we can use, the difference between "Element
hiding -> Advanced selectors" and "Element hiding -> Advanced element hiding"
seems like it would be kind of confusing.

Perhaps it would make more sense to the reader if we call the section "Advanced
pseudo-selectors" or something similar, and work backwards from there to explain
the that the "#?#" syntax is required for those and that the domain restriction
applies for them too? The structure might look something like this:

Advanced pseudo-selectors
  Introductory text explaining the idea, requirement to specify
  a domain, that they are slow etc.

  :-abp-has
  explanation of how that works, a few examples

  :-abp-properties
  explanation of how that works, a few examples

[hub, 2017/07/11 22:25:58]

make sense
 
ok

+
+<p>
+  {{elemhide-emulation-explanation-p1 Advanced hiding rules will hide elements that matches the CSS selector directly. <code><fix>example.com#?#div.textad</fix></code> will directly hide <code><fix>&lt;div&gt;</fix></code> elements with the <code><fix>textad</fix></code> class. These filters only exist as <a href="#generic-specific">specific filters</a>: a domain is mandatory.}}

[kzar, 2017/07/11 12:56:17]

I don't understand what you mean by "matches the CSS selector directly", how is
that different from regular element hiding?

Perhaps, add "For example" before your example filter?

Nit: "match" not "matches".

Nit: The colon after the "specific filters" link seems unnecessary.

I think the last sentence should also explain why it's forbidden to use this
syntax without a domain limitation.

+</p>
+<p>
+  {{elemhide-emulation-explanation-p2 <a href="#elemhide_exceptions">Exception rules</a> above can be applied to the advanced hiding rules the same way.}}

[kzar, 2017/07/11 12:56:17]

This sentence doesn't seem to add much.

[hub, 2017/07/11 22:25:58]

I'll remove this.

+</p>
+<p>
+  {{elemhide-emulation-explanation-p3 Advanced hiding rules also introduce new pseudo-class selectors for when a plain CSS selector isn't enough. <code><fix>:-abp-has(selector)</fix></code> will select the element whose content match the enclosed selector. <code><fix>:-abp-properties(properties)</fix></code> will match elements based on their CSS style properties.}}
+</p>
+<p>
+  {{elemhide-emulation-explanation-p4 <code><fix>:-abp-properties(properties)</fix></code> will select elements based on properties of their stylesheet. For example, <code><fix>:-abp-properties(width:300px;height:250px;)</fix></code> will select elements that have <code><fix>width</fix></code> and <code><fix>height</fix></code> set to the specified values <code><fix>300px</fix></code> and <code><fix>250px</fix></code> respectively. The <a href="https://adblockplus.org/development-builds/new-css-property-filter-syntax">older syntax</a> for the filters is deprecated and will be automatically converted to the new format&nbsp;; the syntax to select the style properties remain the same.}}

[kzar, 2017/07/11 12:56:17]

Nit: It looks wrong to me to put a comma after "For example".

I think you should break the part about the older syntax off into it's own
sentence and format it something like "Note: While the older syntax will
automatically be converted it has been deprecated." Maybe add a small example to
quickly show what the old syntax looks like too?

[hub, 2017/07/11 22:25:58]

Acknowledged.

+</p>
+<p>
+  {{elemhide-emulation-explanation-p5 <code><fix>:-abp-has(selector)</fix></code> will select elements based on their content. For example, <code><fix>:-abp-has(> div > a.advertiser)</fix></code> will select elements that contain as a direct descendant a <code><fix>&lt;div&gt;</fix></code> that contains an <code><fix>&lt;a&gt;</fix></code> with the class <code><fix>advertiser</fix></code>. The inner selector matching determine whether the selection occur. It is important that <code><fix>:-abp-has()</fix></code> be applied to a restricted number of elements to avoid performance issues. Like any regular pseudo-class you can combine it with the CSS selector syntax.}}

[kzar, 2017/07/11 12:56:17]

Perhaps the sentence about limiting the number of elements the :-abp-has applies
to could be moved into the introduction part which explains that these advanced
pseudo-selectors are slow? We could mention that they should be restricted to as
few domains and elements as possible at the same time.

[hub, 2017/07/11 22:25:58]

Acknowledged.

+</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>