Issue 6069 - Add documentation for :-abp-contains() selector

Issue 6069 - Add documentation for :-abp-contains() selector

[juliandoucette, 2017-11-22 21:56:12]

The HTML LGTM.

@Lisa will you double check the content.

@Tamara will you put this into your translation queue.

[tamara, 2017-11-23 09:40:58]

On 2017/11/22 21:56:12, juliandoucette wrote:
> The HTML LGTM.
> 
> @Lisa will you double check the content.
> 
> @Tamara will you put this into your translation queue.

I will need an issue in the Hub or I might forget. If you could please write it,
then Lisa could provide the text that needs to be translated. Is there any date
specified in particular for this?

[Lisa, 2017-11-27 00:18:53]

On 2017/11/23 09:40:58, tamara wrote:
> On 2017/11/22 21:56:12, juliandoucette wrote:
> > The HTML LGTM.
> > 
> > @Lisa will you double check the content.
> > 
> > @Tamara will you put this into your translation queue.
> 
> I will need an issue in the Hub or I might forget. If you could please write
it,
> then Lisa could provide the text that needs to be translated. Is there any
date
> specified in particular for this?

Hi Julian...do you have a deadline for this? Content is swamped at the moment...

[juliandoucette, 2017-11-27 17:05:58]

On 2017/11/27 00:18:53, Lisa wrote:
> Hi Julian...do you have a deadline for this? Content is swamped at the
moment...

None that I know of. It's only 2 lines + 1 medium sized paragraph to edit; if
that helps (assuming you should edit developer documentation changes).

[tamara, 2017-11-27 17:47:27]

On 2017/11/27 17:05:58, juliandoucette wrote:
> On 2017/11/27 00:18:53, Lisa wrote:
> > Hi Julian...do you have a deadline for this? Content is swamped at the
> moment...
> 
> None that I know of. It's only 2 lines + 1 medium sized paragraph to edit; if
> that helps (assuming you should edit developer documentation changes).

I've just been through the files on Crowdin, and the translations for these two
pages are a mess. The /filter-cheatsheet is only translated into Dutch, not even
German. Therefore, requesting the few words for translation for this page will
be a waste of time and money as none of the text will make it to the website
(most languages have 0% of it translated).  :-/

/filters is more than 30% translated into more languages and it could still
work. However, I'd rather have it fully translated properly at some point into
our priority languages, and not just in batches. Spanish right now is just
hideous and reads as if the translator wasn't native at all.

Furthermore, as already mentioned in previous times, it is really difficult for
me to request the text for translation as it currently is in the review due to
the amount of code present.

[juliandoucette, 2017-11-27 18:05:51]

On 2017/11/27 17:47:27, tamara wrote:

Cool, we'll push English and re-translate the entire page later then. Just
waiting on somebody from the content side to say OK.

Sorry about the code review call out. I'll extract the text and create a hub
ticket after it's finalized.

[juliandoucette, 2017-11-27 18:06:37]

Removed Tamara from Reviewers.

[Lisa, 2017-11-27 18:32:11]

Made a few grammatical edits.

To answer your question - yes, the content team should review developer
documentation, too.

https://codereview.adblockplus.org/29615667/diff/29615671/pages/filters.html
File pages/filters.html (right):

https://codereview.adblockplus.org/29615667/diff/29615671/pages/filters.html#...
pages/filters.html:240: {{ elemhide-emulation-1 Sometimes the standard CSS
selectors aren't powerful enough to hide an advertisement, for those cases we
have added some new ones, namely <code><fix>:-abp-has()</fix></code>,
<code><fix>:-abp-contains()</fix></code> and
<code><fix>:-abp-properties()</fix></code> (requires Adblock Plus 1.13.3 for
Chrome and Opera or higher). }}
Sometimes the standard CSS selectors aren't powerful enough to hide an
advertisement. For those cases, we've added some new selectors, namely
<code><fix>:-abp-has()</fix></code>, <code><fix>:-abp-contains()</fix></code>
and <code><fix>:-abp-properties()</fix></code> (requires Adblock Plus 1.13.3 or
higher for Chrome and Opera). }}

https://codereview.adblockplus.org/29615667/diff/29615671/pages/filters.html#...
pages/filters.html:261: {{ abp-contains-1
<code><fix>:-abp-contains(text)</fix></code> will select elements based on their
text content. For example <code><fix>div.sidebar >
span:-abp-contains(Advertisment)</fix></code> will select the 
<code><fix>&lt;span&gt;</fix></code> elements within a
<code><fix>&lt;div&gt;</fix></code> with a class of
<code><fix>sidebar</fix></code> that contains the word "Advertisment". In
practice you'd want to combine this with a <code><fix>:-abp-has()</fix></code>
to select the outer container. Something like <code><fix>div.sidebar >
div:-abp-has(span:-abp-contains(Advertisment))</fix></code> to select the
container that would contain an advertisement label. }}
{{ abp-contains-1 <code><fix>:-abp-contains(text)</fix></code> will select
elements based on their text content. For example, <code><fix>div.sidebar >
span:-abp-contains(Advertisment)</fix></code> will select the 
<code><fix>&lt;span&gt;</fix></code> elements within a
<code><fix>&lt;div&gt;</fix></code>, with a class of
<code><fix>sidebar</fix></code> that contains the word "Advertisment". In
practice, you'd want to combine this with a <code><fix>:-abp-has()</fix></code>
to select the outer container – something like <code><fix>div.sidebar >
div:-abp-has(span:-abp-contains(Advertisment))</fix></code> to select the
container that would contain an advertisement label. }}

[hub, 2017-11-28 19:23:27]

https://codereview.adblockplus.org/29615667/diff/29615671/pages/filters.html
File pages/filters.html (right):

https://codereview.adblockplus.org/29615667/diff/29615671/pages/filters.html#...
pages/filters.html:240: {{ elemhide-emulation-1 Sometimes the standard CSS
selectors aren't powerful enough to hide an advertisement, for those cases we
have added some new ones, namely <code><fix>:-abp-has()</fix></code>,
<code><fix>:-abp-contains()</fix></code> and
<code><fix>:-abp-properties()</fix></code> (requires Adblock Plus 1.13.3 for
Chrome and Opera or higher). }}
On 2017/11/27 18:32:11, Lisa wrote:
> Sometimes the standard CSS selectors aren't powerful enough to hide an
> advertisement. For those cases, we've added some new selectors, namely
> <code><fix>:-abp-has()</fix></code>, <code><fix>:-abp-contains()</fix></code>
> and <code><fix>:-abp-properties()</fix></code> (requires Adblock Plus 1.13.3
or
> higher for Chrome and Opera). }}

Done.

https://codereview.adblockplus.org/29615667/diff/29615671/pages/filters.html#...
pages/filters.html:261: {{ abp-contains-1
<code><fix>:-abp-contains(text)</fix></code> will select elements based on their
text content. For example <code><fix>div.sidebar >
span:-abp-contains(Advertisment)</fix></code> will select the 
<code><fix>&lt;span&gt;</fix></code> elements within a
<code><fix>&lt;div&gt;</fix></code> with a class of
<code><fix>sidebar</fix></code> that contains the word "Advertisment". In
practice you'd want to combine this with a <code><fix>:-abp-has()</fix></code>
to select the outer container. Something like <code><fix>div.sidebar >
div:-abp-has(span:-abp-contains(Advertisment))</fix></code> to select the
container that would contain an advertisement label. }}
On 2017/11/27 18:32:11, Lisa wrote:
> {{ abp-contains-1 <code><fix>:-abp-contains(text)</fix></code> will select
> elements based on their text content. For example, <code><fix>div.sidebar >
> span:-abp-contains(Advertisment)</fix></code> will select the 
> <code><fix>&lt;span&gt;</fix></code> elements within a
> <code><fix>&lt;div&gt;</fix></code>, with a class of
> <code><fix>sidebar</fix></code> that contains the word "Advertisment". In
> practice, you'd want to combine this with a
<code><fix>:-abp-has()</fix></code>
> to select the outer container – something like <code><fix>div.sidebar >
> div:-abp-has(span:-abp-contains(Advertisment))</fix></code> to select the
> container that would contain an advertisement label. }}

Done.

[juliandoucette, 2017-11-29 20:32:17]

LGTM after NIT below.

https://codereview.adblockplus.org/29615667/diff/29622614/pages/filters.html
File pages/filters.html (right):

https://codereview.adblockplus.org/29615667/diff/29622614/pages/filters.html#...
pages/filters.html:261: {{ abp-contains-1
<code><fix>:-abp-contains(text)</fix></code> will select elements based on their
text content. For example, <code><fix>div.sidebar >
span:-abp-contains(Advertisment)</fix></code> will select the 
<code><fix>&lt;span&gt;</fix></code> elements within a
<code><fix>&lt;div&gt;</fix></code>, with a class of
<code><fix>sidebar</fix></code> that contains the word "Advertisment". In
practice, you'd want to combine this with a <code><fix>:-abp-has()</fix></code>
to select the outer container &mdash; something like <code><fix>div.sidebar >
div:-abp-has(span:-abp-contains(Advertisment))</fix></code> to select the
container that would contain an advertisement label. }}
Please use "-" instead of mdash;

[hub, 2017-11-29 22:35:55]

https://codereview.adblockplus.org/29615667/diff/29622614/pages/filters.html
File pages/filters.html (right):

https://codereview.adblockplus.org/29615667/diff/29622614/pages/filters.html#...
pages/filters.html:261: {{ abp-contains-1
<code><fix>:-abp-contains(text)</fix></code> will select elements based on their
text content. For example, <code><fix>div.sidebar >
span:-abp-contains(Advertisment)</fix></code> will select the 
<code><fix>&lt;span&gt;</fix></code> elements within a
<code><fix>&lt;div&gt;</fix></code>, with a class of
<code><fix>sidebar</fix></code> that contains the word "Advertisment". In
practice, you'd want to combine this with a <code><fix>:-abp-has()</fix></code>
to select the outer container &mdash; something like <code><fix>div.sidebar >
div:-abp-has(span:-abp-contains(Advertisment))</fix></code> to select the
container that would contain an advertisement label. }}
On 2017/11/29 20:32:16, juliandoucette wrote:
> Please use "-" instead of mdash;

it was my understanding that &mdash; was the proper dash for that situation.

Fixed.

[juliandoucette, 2017-11-29 23:52:33]

On 2017/11/29 22:35:55, hub wrote:
> it was my understanding that — was the proper dash for that situation.

It is normally. But we've tried to keep not-asci characters out of our text
content. I don't remember why (and will re-evaluate later).

Anyway, since translations will be delayed, you can export + send this to me to
be pushed and I will create a hub issue for future translation.

[Lisa, 2017-11-30 00:50:31]

On 2017/11/29 23:52:33, juliandoucette wrote:
> On 2017/11/29 22:35:55, hub wrote:
> > it was my understanding that — was the proper dash for that situation.
> 
> It is normally. But we've tried to keep not-asci characters out of our text
> content. I don't remember why (and will re-evaluate later).
> 
> Anyway, since translations will be delayed, you can export + send this to me
to
> be pushed and I will create a hub issue for future translation.

I'm not clear on why we have to keep these characters out of our text. We use
en- and emdashes through all of our texts; they shouldn't be replaced with
hyphens.

[juliandoucette, 2017-11-30 01:25:18]

On 2017/11/30 00:50:31, Lisa wrote:
> I'm not clear on why we have to keep these characters out of our text. We use
> en- and emdashes through all of our texts; they shouldn't be replaced with
> hyphens.

[browser, font, cms] support (I just looked into it).

- Browser support is not a problem since abp.org is IE 8+ now (It was IE 6+
before)
- Source Sans Pro supports emdash (tested: https://jsfiddle.net/up737sjv/)
- Our CMS doesn't support UTF8 characters in some cases (this is fixable) - but
you didn't use the UTF8 emdash - so we're fine

Therefore I **can** push the emdash version to abp.org.

Thanks Lisa.

[Lisa, 2017-11-30 01:38:30]

On 2017/11/30 01:25:18, juliandoucette wrote:
> On 2017/11/30 00:50:31, Lisa wrote:
> > I'm not clear on why we have to keep these characters out of our text. We
use
> > en- and emdashes through all of our texts; they shouldn't be replaced with
> > hyphens.
> 
> [browser, font, cms] support (I just looked into it).
> 
> - Browser support is not a problem since http://abp.org is IE 8+ now (It was
IE 6+
> before)
> - Source Sans Pro supports emdash (tested: https://jsfiddle.net/up737sjv/)
> - Our CMS doesn't support UTF8 characters in some cases (this is fixable) -
but
> you didn't use the UTF8 emdash - so we're fine
> 
> Therefore I **can** push the emdash version to http://abp.org.
> 
> Thanks Lisa.

Awesome. Thanks for the clarification!

[juliandoucette, 2017-11-30 01:41:55]

On 2017/11/30 01:25:18, juliandoucette wrote:
> [browser, font, cms] support (I just looked into it).
> 
> - Browser support is not a problem since http://abp.org is IE 8+ now (It was
IE 6+
> before)
> - Source Sans Pro supports emdash (tested: https://jsfiddle.net/up737sjv/)
> - Our CMS doesn't support UTF8 characters in some cases (this is fixable) -
but
> you didn't use the UTF8 emdash - so we're fine
> 
> Therefore I **can** push the emdash version to http://abp.org.
> 
> Thanks Lisa.

In fact, you can use the UTF8 "—" now.

- This is not a case that the CMS does not support
- abp.org HTML has been UTF8 since [my first
commit](https://hg.adblockplus.org/web.adblockplus.org/annotate/38db8c5948ea/templates/default.tmpl#l23)
- the w3c seems to prefer this to escaping [in this
case](https://www.w3.org/International/questions/qa-escapes)

[juliandoucette, 2017-11-30 01:46:12]

CC Ire

@Ire please review my last 3 replies [in case I'm wrong, in order to be
filled-in].

[ire, 2017-11-30 13:15:55]

On 2017/11/30 01:46:12, juliandoucette wrote:
> CC Ire
> 
> @Ire please review my last 3 replies [in case I'm wrong, in order to be
> filled-in].

Seen. Your last answer is correct from what I also know to be true. Since we are
on UTF8, using the actual characters is preferable to escaping.

[hub, 2017-11-30 19:29:29]

On 2017/11/30 13:15:55, ire wrote:

> Seen. Your last answer is correct from what I also know to be true. Since we
are
> on UTF8, using the actual characters is preferable to escaping.

Done. updated patch.

[juliandoucette, 2017-12-01 15:22:15]

On 2017/11/30 19:29:29, hub wrote:
> Done. updated patch.

Thanks hub. Will you email me your commit so that I can push it for you?