Merge pull request #123 from matrix-org/markjh/list_formatting

Fix list formatting

api/client-server/v1/membership.yaml

@@ -52,8 +52,9 @@ paths:
         403:
           description: |-
             You do not have permission to join the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejection are:
-              - The room is invite-only and the user was not invited.
-              - The user has been banned from the room.
+
+            - The room is invite-only and the user was not invited.
+            - The user has been banned from the room.
           examples:
             application/json: |-
               {"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
@@ -119,10 +120,11 @@ paths:
         403:
           description: |-
             You do not have permission to invite the user to the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
-              - The invitee has been banned from the room.
-              - The invitee is already a member of the room.
-              - The inviter is not currently in the room.
-              - The inviter's power level is insufficient to invite users to the room.
+
+            - The invitee has been banned from the room.
+            - The invitee is already a member of the room.
+            - The inviter is not currently in the room.
+            - The inviter's power level is insufficient to invite users to the room.
           examples:
             application/json: |-
               {"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
@@ -164,13 +166,13 @@ paths:
         user ID, the identity server will give the user a list of pending
         invitations, each containing:
 
-          - The room ID to which they were invited
+        - The room ID to which they were invited
 
-          - The token given to the homeserver
+        - The token given to the homeserver
 
-          - A signature of the token, signed with the identity server's private key
+        - A signature of the token, signed with the identity server's private key
 
-          - The matrix user ID who invited them to the room
+        - The matrix user ID who invited them to the room
 
         If a token is requested from the identity server, the home server will
         append a ``m.room.third_party_invite`` event to the room.
@@ -221,10 +223,11 @@ paths:
         403:
           description: |-
             You do not have permission to invite the user to the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
-              - The invitee has been banned from the room.
-              - The invitee is already a member of the room.
-              - The inviter is not currently in the room.
-              - The inviter's power level is insufficient to invite users to the room.
+
+            - The invitee has been banned from the room.
+            - The invitee is already a member of the room.
+            - The inviter is not currently in the room.
+            - The inviter's power level is insufficient to invite users to the room.
           examples:
             application/json: |-
               {"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}

api/client-server/v2_alpha/registration.yaml

@@ -82,9 +82,9 @@ paths:
           description: |-
             Part of the request was invalid. This may include one of the following error codes:
 
-              * ``M_USER_IN_USE`` : The desired user ID is already taken.
-              * ``M_EXCLUSIVE`` : The desired user ID is in the exclusive namespace
-                claimed by an application service.
+            * ``M_USER_IN_USE`` : The desired user ID is already taken.
+            * ``M_EXCLUSIVE`` : The desired user ID is in the exclusive namespace
+              claimed by an application service.
 
             These errors may be returned at any stage of the registration process,
             including after authentication if the requested user ID was registered

specification/client_server_api.rst

@@ -735,23 +735,23 @@ it to be redacted, which may include a reason.
 Upon receipt of a redaction event, the server should strip off any keys not in
 the following list:
 
- - ``event_id``
- - ``type``
- - ``room_id``
- - ``user_id``
- - ``state_key``
- - ``prev_state``
- - ``content``
+- ``event_id``
+- ``type``
+- ``room_id``
+- ``user_id``
+- ``state_key``
+- ``prev_state``
+- ``content``
 
 The content object should also be stripped of all keys, unless it is one of
 one of the following event types:
 
- - ``m.room.member`` allows key ``membership``
- - ``m.room.create`` allows key ``creator``
- - ``m.room.join_rules`` allows key ``join_rule``
- - ``m.room.power_levels`` allows keys ``ban``, ``events``, ``events_default``,
+- ``m.room.member`` allows key ``membership``
+- ``m.room.create`` allows key ``creator``
+- ``m.room.join_rules`` allows key ``join_rule``
+- ``m.room.power_levels`` allows keys ``ban``, ``events``, ``events_default``,
    ``kick``, ``redact``, ``state_default``, ``users``, ``users_default``.
- - ``m.room.aliases`` allows key ``aliases``
+- ``m.room.aliases`` allows key ``aliases``
 
 .. TODO
   Need to update m.room.power_levels to reflect new power levels formatting
@@ -771,9 +771,9 @@ which serves as the root of the event graph for this room. This event also has a
 generate several other events in order to manage permissions in this room. This
 includes:
 
- - ``m.room.power_levels`` : Sets the power levels of users and required power
+- ``m.room.power_levels`` : Sets the power levels of users and required power
    levels for various actions within the room such as sending events.
- - ``m.room.join_rules`` : Whether the room is "invite-only" or not.
+- ``m.room.join_rules`` : Whether the room is "invite-only" or not.
 
 See `Room Events`_ for more information on these events. To create a room, a
 client has to use the the following API.
@@ -847,11 +847,11 @@ Joining rooms
 Users need to be a member of a room in order to send and receive events in that
 room. There are several states in which a user may be, in relation to a room:
 
- - Unrelated (the user cannot send or receive events in the room)
- - Invited (the user has been invited to participate in the room, but is not
-   yet participating)
- - Joined (the user can send and receive events in the room)
- - Banned (the user is not allowed to join the room)
+- Unrelated (the user cannot send or receive events in the room)
+- Invited (the user has been invited to participate in the room, but is not
+  yet participating)
+- Joined (the user can send and receive events in the room)
+- Banned (the user is not allowed to join the room)
 
 There is an exception to the requirement that a user join a room before sending
 events to it: users may send an ``m.room.member`` event to a room with
@@ -942,11 +942,11 @@ many places of a client's display, changes to these fields cause an automatic
 propagation event to occur, informing likely-interested parties of the new
 values. This change is conveyed using two separate mechanisms:
 
- - a ``m.room.member`` event is sent to every room the user is a member of,
-   to update the ``displayname`` and ``avatar_url``.
- - a ``m.presence`` presence status update is sent, again containing the new
-   values of the ``displayname`` and ``avatar_url`` keys, in addition to the
-   required ``presence`` key containing the current presence state of the user.
+- a ``m.room.member`` event is sent to every room the user is a member of,
+  to update the ``displayname`` and ``avatar_url``.
+- a ``m.presence`` presence status update is sent, again containing the new
+  values of the ``displayname`` and ``avatar_url`` keys, in addition to the
+  required ``presence`` key containing the current presence state of the user.
 
 Both of these should be done automatically by the home server when a user
 successfully changes their display name or avatar URL fields.

specification/events.rst

@@ -18,11 +18,11 @@ Size limits
 The total size of any event MUST NOT exceed 65 KB. There are additional
 restrictions on sizes per key:
 
- - ``user_id`` MUST NOT exceed 255 bytes (including domain).
- - ``room_id`` MUST NOT exceed 255 bytes.
- - ``state_key`` MUST NOT exceed 255 bytes.
- - ``type`` MUST NOT exceed 255 bytes.
- - ``event_id`` MUST NOT exceed 255 bytes.
+- ``user_id`` MUST NOT exceed 255 bytes (including domain).
+- ``room_id`` MUST NOT exceed 255 bytes.
+- ``state_key`` MUST NOT exceed 255 bytes.
+- ``type`` MUST NOT exceed 255 bytes.
+- ``event_id`` MUST NOT exceed 255 bytes.
 
 Some event types have additional size restrictions which are specified in
 the description of the event. Additional keys have no limit other than that

specification/modules/content_repo.rst

@@ -64,21 +64,20 @@ UTF-8 encoded traversals, etc).
 
 Homeservers have additional content-specific concerns:
 
- - Clients may try to upload very large files. Homeservers should not store files
-   that are too large and should not serve them to clients.
+- Clients may try to upload very large files. Homeservers should not store files
+  that are too large and should not serve them to clients.
 
- - Clients may try to upload very large images. Homeservers should not attempt to
-   generate thumbnails for images that are too large.
+- Clients may try to upload very large images. Homeservers should not attempt to
+  generate thumbnails for images that are too large.
 
- - Remote homeservers may host very large files or images. Homeservers should not
-   proxy or thumbnail large files or images from remote homeservers.
+- Remote homeservers may host very large files or images. Homeservers should not
+  proxy or thumbnail large files or images from remote homeservers.
 
- - Clients may try to upload a large number of files. Homeservers should limit the
-   number and total size of media that can be uploaded by clients.
+- Clients may try to upload a large number of files. Homeservers should limit the
+  number and total size of media that can be uploaded by clients.
 
- - Clients may try to access a large number of remote files through a homeserver.
-   Homeservers should restrict the number and size of remote files that it caches.
-
- - Clients or remote homeservers may try to upload malicious files targeting
-   vulnerabilities in either the homeserver thumbnailing or the client decoders.
+- Clients may try to access a large number of remote files through a homeserver.
+  Homeservers should restrict the number and size of remote files that it caches.
 
+- Clients or remote homeservers may try to upload malicious files targeting
+  vulnerabilities in either the homeserver thumbnailing or the client decoders.

specification/modules/presence.rst

@@ -5,10 +5,10 @@ Presence
 
 Each user has the concept of presence information. This encodes:
 
- * Whether the user is currently online
- * How recently the user was last active (as seen by the server)
- * Whether a given client considers the user to be currently idle
- * Arbitrary information about the user's current status (e.g. "in a meeting").
+* Whether the user is currently online
+* How recently the user was last active (as seen by the server)
+* Whether a given client considers the user to be currently idle
+* Arbitrary information about the user's current status (e.g. "in a meeting").
 
 This information is collated from both per-device (``online``, ``idle``,
 ``last_active``) and per-user (status) data, aggregated by the user's homeserver
@@ -24,14 +24,14 @@ who must accept the invitation.
 User's presence state is represented by the ``presence`` key, which is an enum
 of one of the following:
 
-      - ``online`` : The default state when the user is connected to an event
-        stream.
-      - ``unavailable`` : The user is not reachable at this time e.g. they are
-        idle.
-      - ``offline`` : The user is not connected to an event stream or is
-        explicitly suppressing their profile information from being sent.
-      - ``free_for_chat`` : The user is generally willing to receive messages
-        moreso than default.
+- ``online`` : The default state when the user is connected to an event
+  stream.
+- ``unavailable`` : The user is not reachable at this time e.g. they are
+  idle.
+- ``offline`` : The user is not connected to an event stream or is
+  explicitly suppressing their profile information from being sent.
+- ``free_for_chat`` : The user is generally willing to receive messages
+  moreso than default.
 
 Events
 ------
@@ -94,10 +94,10 @@ pro-active event from the user. A pro-active event may be sending a message to a
 room or changing presence state to a higher level of availability. Levels of
 availability are defined from low to high as follows:
 
-      - ``offline``
-      - ``unavailable``
-      - ``online``
-      - ``free_for_chat``
+- ``offline``
+- ``unavailable``
+- ``online``
+- ``free_for_chat``
 
 Based on this list, changing state from ``unavailable`` to ``online`` counts as
 a pro-active event, whereas ``online`` to ``unavailable`` does not. This

specification/modules/push.rst

@@ -37,19 +37,19 @@ The above diagram shows the flow of push notifications being sent to a handset
 where push notifications are submitted via the handset vendor, such as Apple's
 APNS or Google's GCM. This happens as follows:
 
- 1. The client app signs in to a homeserver.
- 2. The client app registers with its vendor's Push Provider and
-    obtains a routing token of some kind.
- 3. The mobile app uses the Client/Server API to add a 'pusher', providing the
-    URL of a specific Push Gateway which is configured for that
-    application. It also provides the routing token it has acquired from the
-    Push Provider.
- 4. The homeserver starts sending HTTP requests to the Push Gateway using the
-    supplied URL. The Push Gateway relays this notification to
-    the Push Provider, passing the routing token along with any
-    necessary private credentials the provider requires to send push
-    notifications.
- 5. The Push Provider sends the notification to the device.
+1. The client app signs in to a homeserver.
+2. The client app registers with its vendor's Push Provider and
+   obtains a routing token of some kind.
+3. The mobile app uses the Client/Server API to add a 'pusher', providing the
+   URL of a specific Push Gateway which is configured for that
+   application. It also provides the routing token it has acquired from the
+   Push Provider.
+4. The homeserver starts sending HTTP requests to the Push Gateway using the
+   supplied URL. The Push Gateway relays this notification to
+   the Push Provider, passing the routing token along with any
+   necessary private credentials the provider requires to send push
+   notifications.
+5. The Push Provider sends the notification to the device.
 
 Definitions for terms used in this section are below:
 
@@ -127,16 +127,16 @@ affect delivery of notifications via pushers with a matching ``profile_tag``.
 All device-specific rules have a higher priority than global rules. This means
 that the full list of rule kinds, in descending priority order, is as follows:
 
- * Device-specific Override
- * Device-specific Content
- * Device-specific Room
- * Device-specific Sender
- * Device-specific Underride
- * Global Override
- * Global Content
- * Global Room
- * Global Sender
- * Global Underride
+* Device-specific Override
+* Device-specific Content
+* Device-specific Room
+* Device-specific Sender
+* Device-specific Underride
+* Global Override
+* Global Content
+* Global Room
+* Global Sender
+* Global Underride
 
 Rules with the same ``kind`` can specify an ordering priority. This determines
 which rule is selected in the event of multiple matches. For example, a rule
@@ -315,16 +315,17 @@ rule determines its behaviour. The following conditions are defined:
 
 ``event_match``
   This is a glob pattern match on a field of the event. Parameters:
-   * ``key``: The dot-separated field of the event to match, e.g. ``content.body``
-   * ``pattern``: The glob-style pattern to match against. Patterns with no
-     special glob characters should be treated as having asterisks
-     prepended and appended when testing the condition.
+
+  * ``key``: The dot-separated field of the event to match, e.g. ``content.body``
+  * ``pattern``: The glob-style pattern to match against. Patterns with no
+    special glob characters should be treated as having asterisks
+    prepended and appended when testing the condition.
 
 ``profile_tag``
   Matches the ``profile_tag`` of the device that the notification would be
   delivered to. Parameters:
 
-   * ``profile_tag``: The profile_tag to match with.
+  * ``profile_tag``: The profile_tag to match with.
 
 ``contains_display_name``
   This matches unencrypted messages where ``content.body`` contains the owner's
@@ -334,10 +335,11 @@ rule determines its behaviour. The following conditions are defined:
 
 ``room_member_count``
   This matches the current number of members in the room. Parameters:
-   * ``is``: A decimal integer optionally prefixed by one of, ``==``, ``<``,
-     ``>``, ``>=`` or ``<=``. A prefix of ``<`` matches rooms where the member
-     count is strictly less than the given number and so forth. If no prefix is
-     present, this parameter defaults to ``==``.
+
+  * ``is``: A decimal integer optionally prefixed by one of, ``==``, ``<``,
+    ``>``, ``>=`` or ``<=``. A prefix of ``<`` matches rooms where the member
+    count is strictly less than the given number and so forth. If no prefix is
+    present, this parameter defaults to ``==``.
 
 Push Rules: API
 ~~~~~~~~~~~~~~~
@@ -418,12 +420,12 @@ client app and its' push gateway to agree on. As APNS requires that the sender
 has a private key owned by the app developer, each app must have its own push
 gateway. It is recommended that:
 
- * The APNS token be base64 encoded and used as the pushkey.
- * A different app_id be used for apps on the production and sandbox
-   APS environments.
- * APNS push gateways do not attempt to wait for errors from the APNS
-   gateway before returning and instead to store failures and return
-   'rejected' responses next time that pushkey is used.
+* The APNS token be base64 encoded and used as the pushkey.
+* A different app_id be used for apps on the production and sandbox
+  APS environments.
+* APNS push gateways do not attempt to wait for errors from the APNS
+  gateway before returning and instead to store failures and return
+  'rejected' responses next time that pushkey is used.
 
 Security considerations
 -----------------------

specification/modules/voip_events.rst

@@ -62,19 +62,19 @@ As calls are "placed" to rooms rather than users, the glare resolution algorithm
 outlined below is only considered for calls which are to the same room. The
 algorithm is as follows:
 
- - If an ``m.call.invite`` to a room is received whilst the client is
-   **preparing to send** an ``m.call.invite`` to the same room:
+- If an ``m.call.invite`` to a room is received whilst the client is
+  **preparing to send** an ``m.call.invite`` to the same room:
 
-    * the client should cancel its outgoing call and instead
-      automatically accept the incoming call on behalf of the user.
+  * the client should cancel its outgoing call and instead
+    automatically accept the incoming call on behalf of the user.
 
- - If an ``m.call.invite`` to a room is received **after the client has sent**
-   an ``m.call.invite`` to the same room and is waiting for a response:
+- If an ``m.call.invite`` to a room is received **after the client has sent**
+  an ``m.call.invite`` to the same room and is waiting for a response:
 
-    * the client should perform a lexicographical comparison of the call IDs of
-      the two calls and use the *lesser* of the two calls, aborting the
-      greater. If the incoming call is the lesser, the client should accept
-      this call on behalf of the user.
+  * the client should perform a lexicographical comparison of the call IDs of
+    the two calls and use the *lesser* of the two calls, aborting the
+    greater. If the incoming call is the lesser, the client should accept
+    this call on behalf of the user.
 
 
 The call setup should appear seamless to the user as if they had simply placed