diff --git a/xep-0372.xml b/xep-0372.xml index 5e632eaea..4373c7887 100644 --- a/xep-0372.xml +++ b/xep-0372.xml @@ -25,6 +25,12 @@ Refs &ksmithisode; + + 0.6.0 + 2021-08-25 + jcb + Document how to reference non-body elements + 0.5.0 2020-12-09 @@ -68,14 +74,6 @@

- - - -

If a client implements references, it MUST specify the 'urn:xmpp:reference:0' feature in its service discovery information features as specified in &xep0030; and the Entity Capabilities profile specified in &xep0115;.

The 'begin' and 'end' attributes are indexes denoting the beginning and end of the referenced substring in the message body. The Dijkstra convention of rangesDijkstra convention of ranges <https://www.cs.utexas.edu/users/EWD/transcriptions/EWD08xx/EWD831.html> is used, which means that 'begin' is inclusive and 'end' is exclusive. In other words, the 'begin' attribute is the index of the first unicode code point in the referenced substring, with 0 being the index of the first code point in the body, and the 'end' attribute is one higher than the index of the last code point in the substring. This convention has three main advantages. It matches subsequence indexing in various programming languages, 'end' minus 'begin' equals the length of the substring, and when two substrings are adjacent, the 'end' attribute of the first one matches the 'begin' attribute of the second one. Where the reference is not a substring of the message body in the referring stanza, 'begin' and 'end' are not used.

-

An 'anchor' attribute is used when the referring message is not the one containing the reference element, and points to the previous message containing the reference (the referring message).

-

Note that the URIs of the reference and anchor do not need to refer to the same mechanism as that in which the reference was received. E.g., a service could listen for mentions in a MIX channels of users outside that channel, and send them messages containing a reference to let them know that they've been mentioned.

+

Mentions are a reference to a user's bare JID, and have a type of 'mention'.

]]>
+ + +

By default it's assumed that the text being referenced is inside the 'body' element of the same stanza in which the 'reference' occurs. There are however situations where the referenced text is inside a different stanza, or inside a different element in the same stanza. In these cases, an 'anchor' attribute is used to clarify which element the 'reference' refers to.

+ + +

A stanza might have other text-containing elements besides the 'body', such as the 'subject', 'reason' or 'text' elements. The 'anchor' attribute is used to disambiguate the references in a stanza that has multiple text-containing elements. In this case, the 'anchor' value MUST be a URI fragment which refers to an element in the same stanza (or its value MUST be a full URI with fragment, if the element is in a different stanza). Similarly to HTML, the URI fragment refers to an element with an 'id' attribute that has the same value.

+ + Enter SAMPSON and GREGORY, of the house Capulet, armed with swords and bucklers + Gregory, o' my word, we'll not carry coals + + + ]]> +
+ + +

When the text being referred to is not inside the same stanza, the 'anchor' attribute on the 'reference' is assigned a URI that points to that other stanza.

+

An example of this might be where a MIX channel asynchronously adds information about references made in previous messages by users. In this case the message MUST NOT contain a body. Here the anchor attribute is used to provide a URI to a previous message. TODO: URI scheme for messages.

+ + + + ]]> +
+ +
+

Data references are a generic reference without additional information. The URI points to an 'item' that is able to be fetched. This is useful for, for example, fetching an item from pubsub, as in the example below. TODO: check URI syntax for refering to a pubsub item.

-]]> -
- -

Sometimes it's desirable to annotate a reference in a previous message. An example of this might be where a MIX channel asynchronously adds information about references made in previous messages by users. In this case the message MUST NOT contain a body. Here the anchor attribute is used to provide a URI to the previous message. TODO: URI scheme for messages.

- - - ]]>