-
Notifications
You must be signed in to change notification settings - Fork 122
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
XEP-0372: Document how to reference non-body elements
- Loading branch information
Showing
1 changed file
with
49 additions
and
26 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -25,6 +25,12 @@ | |
| <supersededby/> | ||
| <shortname>Refs</shortname> | ||
| &ksmithisode; | ||
| <revision> | ||
| <version>0.6.0</version> | ||
| <date>2021-08-25</date> | ||
| <initials>jcb</initials> | ||
| <remark>Document how to reference non-body elements</remark> | ||
| </revision> | ||
| <revision> | ||
| <version>0.5.0</version> | ||
| <date>2020-12-09</date> | ||
|
|
@@ -68,14 +74,6 @@ | |
| </p> | ||
| </section1> | ||
|
|
||
| <!--<section1 topic='Requirements' anchor='reqs'> | ||
| <ul> | ||
| <li></li> | ||
| </ul> | ||
| </section1>--> | ||
|
|
||
|
|
||
|
|
||
| <section1 topic='Discovery' anchor='discovery'> | ||
| <p>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;.</p> | ||
| <example caption='Client queries for contact's features'><![CDATA[ | ||
|
|
@@ -108,9 +106,8 @@ | |
| <p>The 'begin' and 'end' attributes are indexes denoting the beginning and end of the referenced substring in the message body. The Dijkstra convention of ranges<note>Dijkstra convention of ranges <<link url='https://www.cs.utexas.edu/users/EWD/transcriptions/EWD08xx/EWD831.html'>https://www.cs.utexas.edu/users/EWD/transcriptions/EWD08xx/EWD831.html</link>></note> 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.</p> | ||
| <p>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).</p> | ||
| <p>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.</p> | ||
| </section2> | ||
|
|
||
| <section2 topic='Mentions' anchor='usecase_mention'> | ||
| <p>Mentions are a reference to a user's bare JID, and have a type of 'mention'.</p> | ||
| <example caption='Romeo sends a message mentioning Juliet'><![CDATA[ | ||
|
|
@@ -126,6 +123,48 @@ | |
| </message> | ||
| ]]></example> | ||
| </section2> | ||
|
|
||
| <section2 topic='Anchors' anchor='anchors'> | ||
| <p>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.</p> | ||
|
|
||
| <section3 topic='Specifying which text a reference refers to' anchor='usecase_other_text'> | ||
| <p>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.</p> | ||
| <example caption='A reference that refers to text inside the subject, not the body'><![CDATA[ | ||
| <message type='headline' | ||
| id='a8hef4-99hct232h0' | ||
| from='[email protected]'> | ||
| <subject id="subject-id">Enter SAMPSON and GREGORY, of the house Capulet, armed with swords and bucklers</subject> | ||
| <body>Gregory, o' my word, we'll not carry coals</body> | ||
| <reference xmlns='urn:xmpp:reference:0' | ||
| begin='6' | ||
| end='13' | ||
| type='mention' | ||
| anchor='#subject-id' | ||
| uri='xmpp:[email protected]'/> | ||
| </message> | ||
| ]]></example> | ||
| </section3> | ||
|
|
||
| <section3 topic='Anchors to previous messages' anchor='usecase_previous'> | ||
| <p>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.</p> | ||
| <p>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.</p> | ||
| <example caption='A MIX Channel annotates a previous user message'><![CDATA[ | ||
| <message type='groupchat' | ||
| id='sotehu-bthbtp32h5' | ||
| from='[email protected]' | ||
| to='[email protected]/30d3d8'> | ||
| <reference xmlns='urn:xmpp:reference:0' | ||
| type='data' | ||
| anchor='xmpp:[email protected]?;node=messages;item=bnhob' | ||
| begin='72' | ||
| end='78' | ||
| uri='xmpp:fdp.shakespeare.lit?;node=fdp/submitted/stan.isode.net/accidentreport;item=ndina872be'/> | ||
| </message> | ||
| ]]></example> | ||
| </section3> | ||
|
|
||
| </section2> | ||
|
|
||
| <section2 topic='Data' anchor='usecase_data'> | ||
| <p>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.</p> | ||
| <example caption='A MIX Channel sends a message that a new FDP form has been submitted elsewhere'><![CDATA[ | ||
|
|
@@ -138,22 +177,6 @@ | |
| type='data' | ||
| uri='xmpp:fdp.shakespeare.lit?;node=fdp/submitted/stan.isode.net/accidentreport;item=ndina872be'/> | ||
| </message> | ||
| ]]></example> | ||
| </section2> | ||
| <section2 topic='Previous messages' anchor='usecase_previous'> | ||
| <p>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.</p> | ||
| <example caption='A MIX Channel annotates a previous user message'><![CDATA[ | ||
| <message type='groupchat' | ||
| id='sotehu-bthbtp32h5' | ||
| from='[email protected]' | ||
| to='[email protected]/30d3d8'> | ||
| <reference xmlns='urn:xmpp:reference:0' | ||
| type='data' | ||
| anchor='xmpp:[email protected]?;node=messages;item=bnhob' | ||
| begin='72' | ||
| end='78' | ||
| uri='xmpp:fdp.shakespeare.lit?;node=fdp/submitted/stan.isode.net/accidentreport;item=ndina872be'/> | ||
| </message> | ||
| ]]></example> | ||
| </section2> | ||
|
|
||
|
|
||