Document how mentions (pills) work

Implements the proposal over at matrix-org#1067

Includes some specification for how matrix.to is structured, and how it is intended to be replaced.

specification/appendices/identifier_grammar.rst

@@ -1,5 +1,5 @@
 .. Copyright 2016 Openmarket Ltd.
-.. Copyright 2017 New Vector Ltd.
+.. Copyright 2017, 2018 New Vector Ltd.
 ..
 .. Licensed under the Apache License, Version 2.0 (the "License");
 .. you may not use this file except in compliance with the License.
@@ -252,3 +252,33 @@ domain).
 
 .. TODO-spec
   - Need to specify precise grammar for Room Aliases. https://matrix.org/jira/browse/SPEC-391
+
+matrix.to navigation
+++++++++++++++++++++
+
+.. NOTE:
+   This namespacing is in place pending a ``matrix://`` (or similar) URI scheme.
+
+Rooms, users, aliases, and groups may be represented as a "matrix.to" URI.
+This URI can be used to reference particular objects in a given context, such
+as mentioning a user in a message or linking someone to a particular point
+in the room's history (a permalink).
+
+A matrix.to URI has the following format, based upon the specification defined
+in RFC 3986:
+
+  https://matrix.to/#/<identifier>/<extra parameter>
+
+The identifier may be a room ID, room alias, user ID, or group ID. The extra
+parameter is only used in the case of permalinks where an event ID is referenced.
+The matrix.to URI, when referenced, must always start with ``https://matrix.to/#/``
+followed by the identifier. 
+
+Examples of matrix.to URIs are:
+
+* Room: ``https://matrix.to/#/!somewhere:domain.com``
+* Room alias: ``https://matrix.to/#/#somewhere:domain.com``
+* Permalink by room: ``https://matrix.to/#/!somewhere:domain.com/$event:example.org``
+* Permalink by room alias: ``https://matrix.to/#/#somewhere:domain.com/$event:example.org``
+* User: ``https://matrix.to/#/@alice:example.org``
+* Group: ``https://matrix.to/#/+example:domain.com``

specification/modules/mentions.rst

@@ -0,0 +1,70 @@
+.. Copyright 2018 New Vector Ltd.
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+..     http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+User, room, and group mentions
+==============================
+
+.. _module:mentions:
+
+This module allows users to mention other users, rooms, and groups within
+a room message. This is achieved by including a `matrix.to URI`_ in the HTML
+body of an `m.room.message`_ event. This module does not have any server-specific
+behaviour to it.
+
+Mentions apply only to `m.room.message`_ events where the ``msgtype`` is ``m.text``,
+``m.emote``, or ``m.notice``. The ``format`` for the event must be ``org.matrix.custom.html``
+and therefore requires a ``formatted_body``.
+
+To make a mention, reference the entity being mentioned in the ``formatted_body``
+using an anchor, like so::
+
+    {
+        "body": "Hello Alice!",
+        "msgtype": "m.text",
+        "format": "org.matrix.custom.html",
+        "formatted_body": "Hello <a href='https://matrix.to/#/@alice:example.org>Alice</a>!"
+    }
+
+
+Client behaviour
+----------------
+
+In addition to using the appropriate ``matrix.to URI`` for the mention,
+clients should use the following guidelines when making mentions:
+
+* When mentioning users, use the user's potentially ambigious display name for
+  the anchor's text. If the user does not have a display name, use the user's
+  ID.
+
+* When mentioning rooms, use the canonical alias for the room. If the room
+  does not have a canonical alias, prefer one of the aliases listed on the
+  room. If no alias can be found, fall back to the room ID. In all cases,
+  use the alias/room ID being linked to as the anchor's text.
+
+* When referencing groups, use the group ID as the anchor's text.
+
+The text component of the anchor should be used in the event's ``body`` where
+the mention would normally be represented, as shown in the example above.
+
+Clients should display mentions differently from other elements. For example,
+this may be done by changing the background color of the mention to indicate
+that it is different from a normal link. 
+
+If the current user is mentioned in a message (either by a mention as defined
+in this module or by a push rule), the client should show that mention differently
+from other mentions, such as by using a red background color to signify to the
+user that they were mentioned.
+
+When clicked, the mention should navigate the user to the appropriate room, group,
+or user information.

specification/targets.yaml

@@ -67,6 +67,7 @@ groups:  # reusable blobs of files when prefixed with 'group:'
     - modules/report_content.rst
     - modules/third_party_networks.rst
     - modules/openid.rst
+    - modules/mentions.rst
 
 
 title_styles: ["=", "-", "~", "+", "^", "`", "@", ":"]