Improve presentation of push rules kinds and actions (#1348)

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;
-}
+}
+
+/* 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 <code> elements matching
+ * .td-content { p code, li > code, table code }.
+ * Copy those styles here to apply to code <elements> 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.
+  }
+}

changelogs/client_server/newsfragments/1348.clarification

@@ -0,0 +1 @@
+Improve the presentation of push rule kinds and actions.

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