diff --git a/assets/scss/custom.scss b/assets/scss/custom.scss index 528af5a0..1534d5bd 100644 --- a/assets/scss/custom.scss +++ b/assets/scss/custom.scss @@ -473,4 +473,32 @@ Make padding symmetrical (this selector is used in the default styles to apply p background-position: left 1rem center; background-repeat: no-repeat; padding-left: 100px; -} \ No newline at end of file +} + +/* Adjust the styling of definition lists. */ + +/* Add a little spacing between the term and its definition. */ +dt { + margin-bottom: 0.15rem; +} + +/* _reboot.scss deliberately sets margin-left to 0. Undo this. */ +dd { + margin-left: 2rem; +} + +/* docsy's _code.scss does only styles elements matching + * .td-content { p code, li > code, table code }. + * Copy those styles here to apply to code in definition terms too. */ + +.td-content { + dt code { + color: inherit; + padding: 0.2em 0.4em; + margin: 0; + font-size: 85%; + word-break: normal; + background-color: rgba($black, 0.05); + border-radius: 0.25rem; // was $border-radius, but that var isn't accessible here. + } +} diff --git a/changelogs/client_server/newsfragments/1348.clarification b/changelogs/client_server/newsfragments/1348.clarification new file mode 100644 index 00000000..000ef5f7 --- /dev/null +++ b/changelogs/client_server/newsfragments/1348.clarification @@ -0,0 +1 @@ +Improve the presentation of push rule kinds and actions. diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index be09921b..33652113 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -144,27 +144,27 @@ the value of `kind`. The different `kind`s of rule, in the order that they are checked, are: -Override Rules `override` -The highest priority rules are user-configured overrides. +1. **Override rules (`override`).** + The highest priority rules are user-configured overrides. -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`. +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`. -Room-specific Rules `room` -These rules change the behaviour of all messages for a given room. The -`rule_id` of a room rule is always the ID of the room that it affects. +1. **Room-specific rules (`room`).** + These rules change the behaviour of all messages for a given room. The + `rule_id` of a room rule is always the ID of the room that it affects. -Sender-specific rules `sender` -These rules configure notification behaviour for messages from a -specific Matrix user ID. The `rule_id` of Sender rules is always the -Matrix user ID of the user whose messages they'd apply to. +1. **Sender-specific rules (`sender`).** + These rules configure notification behaviour for messages from a + specific Matrix user ID. The `rule_id` of Sender rules is always the + Matrix user ID of the user whose messages they'd apply to. -Underride rules `underride` -These are identical to `override` rules, but have a lower priority than -`content`, `room` and `sender` rules. +1. **Underride rules (`underride`).** + These are identical to `override` rules, but have a lower priority than + `content`, `room` and `sender` rules. Rules with the same `kind` can specify an ordering priority. This determines which rule is selected in the event of multiple matches. For @@ -186,48 +186,56 @@ how a notification is delivered for a matching event. The following actions are defined: `notify` -This causes each matching event to generate a notification. + +: This causes each matching event to generate a notification. `dont_notify` -This prevents each matching event from generating a notification + +: This prevents each matching event from generating a notification. `coalesce` -This enables notifications for matching events but activates homeserver -specific behaviour to intelligently coalesce multiple events into a -single notification. Not all homeservers may support this. Those that do -not support it should treat it as the `notify` action. + +: This enables notifications for matching events but activates homeserver + specific behaviour to intelligently coalesce multiple events into a + single notification. Not all homeservers may support this. Those that do + not support it should treat it as the `notify` action. `set_tweak` -Sets an entry in the `tweaks` dictionary key that is sent in the -notification request to the Push Gateway. This takes the form of a -dictionary with a `set_tweak` key whose value is the name of the tweak -to set. It may also have a `value` key which is the value to which it -should be set. - -The following tweaks are defined: - -* `sound`: A string representing the sound to be played when this notification -arrives. A value of `default` means to play a default sound. A device -may choose to alert the user by some other means if appropriate, eg. -vibration. - -* `highlight`: A boolean representing whether or not this message should be highlighted -in the UI. This will normally take the form of presenting the message in -a different colour and/or style. The UI might also be adjusted to draw -particular attention to the room in which the event occurred. If a -`highlight` tweak is given with no value, its value is defined to be -`true`. If no highlight tweak is given at all then the value of -`highlight` is defined to be false. - -Tweaks are passed transparently through the homeserver so client -applications and Push Gateways may agree on additional tweaks. For -example, a tweak may be added to specify how to flash the notification -light on a mobile device. + +: Sets an entry in the `tweaks` dictionary key that is sent in the + notification request to the Push Gateway. This takes the form of a + dictionary with a `set_tweak` key whose value is the name of the tweak + to set. It may also have a `value` key which is the value to which it + should be set. + + The following tweaks are defined: + + `sound` + + : A string representing the sound to be played when this notification + arrives. A value of `default` means to play a default sound. A device + may choose to alert the user by some other means if appropriate, eg. + vibration. + + `highlight` + + : A boolean representing whether or not this message should be highlighted + in the UI. This will normally take the form of presenting the message in + a different colour and/or style. The UI might also be adjusted to draw + particular attention to the room in which the event occurred. If a + `highlight` tweak is given with no value, its value is defined to be + `true`. If no highlight tweak is given at all then the value of + `highlight` is defined to be false. + + Tweaks are passed transparently through the homeserver so client + applications and Push Gateways may agree on additional tweaks. For + example, a tweak may be added to specify how to flash the notification + light on a mobile device. Actions that have no parameters are represented as a string. Otherwise, they are represented as a dictionary with a key equal to their name and other keys as their parameters, e.g. -`{ "set_tweak": "sound", "value": "default" }` +`{ "set_tweak": "sound", "value": "default" }`. ###### Conditions