Clarify what key content-specific rules match against. (#1441)

changelogs/client_server/newsfragments/1441.clarification

@@ -0,0 +1 @@
+Clarify what event property the content-specific push rules match against.

content/appendices.md

@@ -934,6 +934,14 @@ The `address` is the telephone number represented as a MSISDN (Mobile
 Station International Subscriber Directory Number) as defined by the
 E.164 numbering plan. Note that MSISDNs do not include a leading '+'.
 
+## Glob-style matching
+
+It is useful to match strings via globbing in some situations. Globbing in Matrix
+uses the following rules:
+
+* The character `*` matches zero or more characters.
+* `?` matches exactly one character.
+
 ## Security Threat Model
 
 ### Denial of Service

content/client-server-api/modules/moderation_policies.md

@@ -75,8 +75,8 @@ technique for receiving updates to the policy's rules.
 
 #### Events
 
-The `entity` described by the state events can contain `*` and `?` to
-match zero or more characters and exactly one character respectively. Note that
+The `entity` described by the state events is interpreted as a
+[glob-style pattern](/appendices#glob-style-matching). Note that
 rules against rooms can describe a room ID or room alias - the
 subscriber is responsible for resolving the alias to a room ID if
 desired.

content/client-server-api/modules/push.md

@@ -155,8 +155,12 @@ The different `kind`s of rule, in the order that they are checked, are:
 1.  **Content-specific rules (`content`).**
     These configure behaviour for (unencrypted) messages that match certain
     patterns. Content rules take one parameter: `pattern`, that gives the
-    glob pattern to match against. This is treated in the same way as
-    `pattern` for `event_match`.
+    [glob-style pattern](/appendices#glob-style-matching) to match against.
+    The match is performed case-insensitively, and must match any substring of
+    the `content.body` property which starts and ends at a word boundary. A word
+    boundary is defined as the start or end of the value, or any character not
+    in the sets `[A-Z]`, `[a-z]`, `[0-9]` or `_`.The exact meaning of
+    "case insensitive" is defined by the implementation of the homeserver.
 
 1.  **Room-specific rules (`room`).**
     These rules change the behaviour of all messages for a given room. The
@@ -264,18 +268,13 @@ This is a glob pattern match on a field of the event. Parameters:
 -   `key`: The dot-separated path of the property of the event to match, e.g.
     `content.body`.
 
--   `pattern`: The glob-style pattern to match against.
+-   `pattern`: The [glob-style pattern](/appendices#glob-style-matching) to match against.
 
 The match is performed case-insensitively, and must match the entire value of
 the event field given by `key` (though see below regarding `content.body`). The
 exact meaning of "case insensitive" is defined by the implementation of the
 homeserver.
 
-Within `pattern`:
-
-  * The character `*` matches zero or more characters.
-  * `?` matches exactly one character.
-
 If the property specified by `key` is completely absent from the event, or does
 not have a string value, then the condition will not match, even if `pattern`
 is `*`.

data/api/client-server/definitions/push_condition.yaml

@@ -34,8 +34,8 @@ properties:
   pattern:
     type: string
     description: |-
-      Required for `event_match` conditions. The glob-style pattern to
-      match against.
+      Required for `event_match` conditions. The [glob-style pattern](/appendices#glob-style-matching)
+      to match against.
   is:
     type: string
     description: |-

data/api/client-server/definitions/push_rule.yaml

@@ -46,8 +46,8 @@ properties:
   pattern:
     type: string
     description: |-
-      The glob-style pattern to match against.  Only applicable to `content`
-      rules.
+      The [glob-style pattern](/appendices#glob-style-matching) to match against.
+      Only applicable to `content` rules.
 required:
   - actions
   - default

data/event-schemas/schema/m.room.server_acl.yaml

@@ -7,8 +7,8 @@ description: |-
   server ACL. Servers that do not uphold the ACLs MUST be added to the denied hosts
   list in order for the ACLs to remain effective.
 
-  The `allow` and `deny` lists are lists of globs supporting `?` and `*`
-  as wildcards. When comparing against the server ACLs, the suspect server's port
+  The `allow` and `deny` lists are lists of [glob-style patterns](/appendices#glob-style-matching).
+  When comparing against the server ACLs, the suspect server's port
   number must not be considered. Therefore `evil.com`, `evil.com:8448`, and
   `evil.com:1234` would all match rules that apply to `evil.com`, for example.
 
@@ -61,8 +61,7 @@ properties:
         type: array
         description: |-
           The server names to allow in the room, excluding any port information.
-          Wildcards may be used to cover a wider range of hosts, where `*`
-          matches zero or more characters and `?` matches exactly one character.
+          Each entry is interpreted as a [glob-style pattern](/appendices#glob-style-matching).
 
           **This defaults to an empty list when not provided, effectively disallowing
           every server.**
@@ -72,8 +71,7 @@ properties:
         type: array
         description: |-
           The server names to disallow in the room, excluding any port information.
-          Wildcards may be used to cover a wider range of hosts, where `*`
-          matches zero or more characters and `?` matches exactly one character.
+          Each entry is interpreted as a [glob-style pattern](/appendices#glob-style-matching).
 
           This defaults to an empty list when not provided.
         items: