Add content_filters doc (might require another edit)

2024-09-19 15:55:13 +00:00 · 2023-09-12 14:02:01 +10:00 · 2023-09-12 14:02:01 +10:00 · f110785d1f
commit f110785d1f
parent 2c9c3cb690
1 changed files with 98 additions and 0 deletions
--- a/doc/guide/en/Content_Filters.mc
+++ b/doc/guide/en/Content_Filters.mc
@ -0,0 +1,98 @@
+Content Filters
+===============
+
+
+### Overview
+
+The **Content Filter** app (when installed) allows you to filter incoming content from all sources or from specific connections. The filtering may be based on words, tags, regular expressions, or language.
+
+You can set global filters for all incoming content in the Content Filter app.
+
+You can also set individual filters for each of your Connections. Select "Edit" for any connection, then look under Custom Filter.
+
+If you add filters under **Do not import posts with this text**, these are applied first. Any matching content will be removed.
+
+Then, any filters under **Only import posts with this text** are applied. Only matching content will be kept, and everything that doesn't match will be removed.
+
+
+### Basic Filters
+
+**TEXT**
+
+**Any text that doesn't start with one of the following: lang= lang!= # $ ? /**
+Case-insensitive text match
+Example: `covid` (matches "covid", "COVID", "Covid", etc)
+
+
+**LANGUAGE**
+
+**lang=**
+Match language if it can be identified
+Example: `lang=de` (matches German-language content)
+
+**lang!=**
+Anything except this language
+Example: `lang!=en` (matches non-English content)
+
+
+**HASHTAG**
+
+**#[zrl=https://forum.statler.ws/search?tag=%2A%2A]**[/zrl]
+Match hashtag
+Example: `#[zrl=https://forum.statler.ws/search?tag=cats%60]cats`[/zrl]
+
+
+**CATEGORY**
+
+**$**
+Match category (requires installing the **Categories** app). Categories are "personal hashtags" that do not generally federate with other instances.
+Example: `$Science`
+
+
+**ITEMS AND FIELDS**
+
+**?**
+Discussed below under **Advanced Filters**
+
+
+**REGULAR EXPRESSIONS (REGEX)**
+
+**/**
+Match a "regular expression". See numerous online help sites such as [Regular-Expressions.info](https://www.regular-expressions.info/) for regex assistance.
+Example: `/gr[ae]y/` (matches "gray" and "grey")
+
+
+### Advanced Filters
+
+**ITEMS**
+
+**?**
+You can do a string/numeric/array/boolean match on the database fields of an item (a post, comment, etc). A complete listing is beyond the scope of this document, but see `install/schema_mysql.sql` and search for `CREATE TABLE IF NOT EXISTS [nomd]`[/nomd]item[nomd]`[/nomd]`. Here is a sampling:
+* `body` (text of the message)
+* `verb` (what this item does)
+* `item_thread_top` (first post in a thread, boolean)
+* `item_private` (0 = public message, 1 = restricted message, 2 = direct message)
+* ...etc...
+
+Available comparison operators are:
+* `?foo ~= baz` -- item.foo contains the string 'baz'
+* `?foo == baz` -- item.foo is the string 'baz'
+* `?foo != baz` -- item.foo is not the string 'baz'
+* `?foo >= 3` -- item.foo is greater than or equal to 3
+* `?foo > 3` -- item.foo is greater than 3
+* `?foo <= 3` -- item.foo is less than or equal to 3
+* `?foo < 3` -- item.foo is less than 3
+* `?foo {} baz` -- 'baz' is an array element in item.foo
+* `?foo {\*} baz` -- 'baz' is an array key in item.foo
+* `?foo` -- true condition for item.foo
+* `?!foo` -- false condition for item.foo (The values 0, '', an empty array, and an unset value will all evaluate to false)
+
+Example: `?verb == Announce` (matches ActivityPub "boosts")
+
+
+**FIELDS**
+
+**?+**
+Field match: ?+field item.object
+*Usage is undocumented at present*[/share]
+@[zrl=https://forum.statler.ws/channel/billstatler]Bill Statler[/zrl]