Explain basic syntax in the my filters docs, docsUX

[Eccenux]

Prerequisites

• I verified that this is not a filter list issue. Report any issues with filter lists or broken website functionality in the uAssets issue tracker.
• This is NOT a YouTube, Facebook or Twitch report. These sites MUST be reported by clicking their respective links.
• This is not a support issue or a question. For support, questions, or help, visit /r/uBlockOrigin.
• I performed a cursory search of the issue tracker to avoid opening a duplicate issue.
• The issue is not present after disabling uBO in the browser.
• I checked the documentation to understand that the issue I am reporting is not normal behavior.

I tried to reproduce the issue when...

• uBO is the only extension.
• uBO uses default lists and settings.
• using a new, unmodified browser profile.

Description

Explain basic syntax in the docs, set the expectations.

A specific URL where the issue occurs.

https://github.com/gorhill/uBlock/wiki/Dashboard:-My-filters

Steps to Reproduce

1. Settings.
2. My filters (moz-extension://.../dashboard.html#1p-filters.html).
3. Docs icon -> https://github.com/gorhill/uBlock/wiki/Dashboard:-My-filters

Expected behavior

Explain the syntax roughly, point to more details. Explain the options later.

Perhaps explain what to expect in current article (abstract aka summary aka TL;DR).

Or link to another page that does that.

Actual behavior

Above the fold I can only see a trusted filter screen.

Even reading the rest of this page it is impossible to get the feeling of what the filters are and what they can do. So show a few examples from simple to advanced.

So perhaps something like this:

My filters

...Abstract perhaps?...

TOC

Syntax of filters

Let's start with a simple example:
http://example.com/abs.js
This will block this specific URL as written and all URLs that start with that so also http://example.com/abs.js/abc.

||example.com/abs.js
Will be protocol independent so both http:// and https:// will be blocked. The || is a modifier prefix.

You could also use @@ to make an accept-filter (by default filters are blocking). Note that accept filters are more important then blocking filters.

So the syntax is:

{`modifier prefixes`}{`url` or `regexp`]${`options` (separated by a comma)}

See more about the syntax in: Static filter syntax.

The warning

...

Order of filters

Note that what you enter in "My filters" might be overriden by other filters. See the logger to check which filter was applied.

Remember that accept filters are more important then blocking filters. So to block an url that has an accept filter you will need to use the important option.

Options

[the screen that is now on top]
...the rest as-is...

Notes

• Not sure if I named the parts correctly you might want to adjust. I haven't found this.
• Not sur if there needs to be variants of this syntax. Haven't looked at AST/tokens.

uBO version

1.68.0

Browser name and version

Firefox: 149

Operating System and version

Win11pro 25H2

[Eccenux]

Sorry for typos. I was watching 25th Wikipedia Birthday Party with one of my eyes 😉.

[gothic-bum]

Linked at the top of https://github.com/gorhill/uBlock/wiki/Dashboard:-My-filters

• My filters
  • Static filter syntax
    • Procedural cosmetic filters
    • Resources Library

Clicking on these links will provide the user with information about filter syntax and options.

And at the top of the page for Static filter syntax :

uBlock Origin (uBO) supports most of the EasyList filter syntax. You can refer to existing filter syntax documentation from Adblock Plus (ABP) and AdGuard (AG).

These links provide detailed information about filter syntax and instructions with examples for how to write filters.

[Eccenux]

AdGuard docs are quite good, but that is an AdGuard documentation. Can you point to where uBO describes the syntax the way it is described here?
https://adguard.com/kb/general/ad-filtering/create-own-filters/

[gothic-bum]

The information in the links for EasyList/ABP filter syntax is applicable to uBO.

uBO-specific filter syntax is described in the page for Static filter syntax.

[Eccenux]

That syntax page is 104k character long (about 33k words). And also the link from uBlock is not to that page. It links to My filters page.

[Eccenux]

To be clear my point is that there seem to be no uBo page that describes the syntax in general terms before going into a lot of details. It goes straight into details.

[freezer2022]

It seems that despite OP was pointed out in the previous thread: #3917 to read documentation more carefully and with understanding, he has still missed https://github.com/gorhill/uBlock/wiki/About-the-Wiki-documentation which is located almost on the top, and which says to post uBO documentation related suggestions in Dicussions and not in Issue Tracker (to be clear: the thread has been moved from Issues to Discussions). This proves again that it's not the documentation which is a problem here, but reading it carefully and with understanding, by some users. (nothing personal, just stating some facts peacefully).

[Eccenux]

I did miss that part about posting suggestions for docs in Discussions rather than the Issue Tracker, true. Not sure why that’s relevant, though. Is your point that I didn’t read the entire documentation? I didn't, that's true.

Now that we have that out of the way I want to say that I know most people don’t read the entire documentation. I’ve been in IT for about 30 years now. I created the EasyMOD FAQ for phpBB, I’ve been a Wikipedia user for 20 years, and I’m currently an administrator of Wikipedia and a mentor. I also worked on a phone in IT for something like 5 years and created a lot of documentation for both lay people as well as IT pros (for large and small library admins). People don’t usually read all the docs when they encounter a problem – they look for relevant information. That’s why clear documentation structure is important. It's also important to make it easier to scan the documentation for relevant information.

Also, even on Reddit, two experienced users didn’t know I had to use $important to override @@ rules from the default filters. They didn't even suggest to use the logger UI. I think it’s fair to assume that’s not something that obvious to people, and it should probably be made clearer how "My filters" work.

[Eccenux]

What? Why is this closed now? I though my suggestions were mostly clear. You can copy paste most of that and use on the my filters page. Perhaps correct the wording a bit.

[gothic-bum]

https://adguard.com/kb/general/ad-filtering/create-own-filters/#basic-rules-syntax

https://github.com/gorhill/uBlock/wiki/Static-filter-syntax#static-extended-filtering

https://github.com/gorhill/uBlock/wiki/Static-filter-syntax#cosmetic-filters

[freezer2022]

Eccenux: I did miss that part about posting suggestions for docs in Discussions rather than the Issue Tracker, true. Not sure why that’s relevant, though. Is your point that I didn’t read the entire documentation? I didn't, that's true.

Not exactly, the point is to just read only those pages that seem necessary / reasonable at a given moment, optionally to use the search feature. In this specific case, there exists only a single page about WiKi itself, almost on the top of WiKi, therefore it seems it would be reasonable / appropriate / logical and expected to read it as a starting point, before posting suggestions about Wiki. The similar rule applies for all other matters.

Eccenux: OK, can you point to where it is describe in short terms? Like what are the parts of a filter?

• https://adblockplus.org/filter-cheatsheet
• https://adguard.com/kb/general/ad-filtering/create-own-filters/#examples

Just a bit of effort and it's possible to find everything explained.

[Eccenux]

Sigh. I mean, I still think I was quite clear that I wanted to improve uBO documentation ¯_(ツ)_/¯. Not AdGuard nor Adblock documentation, uBO docs. I don't know why you refuse to admit there are problems, yet when pressed, you keep pointing me to some external docs. I don't know, I guess there’s some communication problem.

Anyway, I’ll still be happy if you just keep supporting the add-on I use. I'll just write something about this on Wikipedia instead. Have a good rest of your day or night.

[stephenhawk8054]

We said

You can refer to existing filter syntax documentation from Adblock Plus (ABP) and AdGuard (AG).

which means we won't do those parts on our end. They are companies, they have resources to do that. We are volunteers, resolving the websites' issues everyday take most of our little free time already.

---

why you refuse to admit there are problems

That's your opinions, not ours.

[freezer2022]

Eccenux: Sigh. I mean (...)

Well, I understood it in the context that you still wanted to point out to gorhill that the uBO documentation lacks some basic guide, perhaps you were not clear enought with the context, or maybe it was me who got the wrong context, optionally both of ours faults, have no idea who's is this fault, I'll let others judge that.

Eccenux: I don't know why you refuse to admit there are problems

I don't think that I / we refuse anything, it's just that what you describes isn't a problem for us, and seems to be a problem only for you and the other guy from the previous thread.