Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

XEP-0372: Document how to reference non-body elements #1102

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

XEP-0372: Document how to reference non-body elements #1102

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 49 additions & 26 deletions xep-0372.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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&apos;s features'><![CDATA[
Expand Down Expand Up @@ -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 &lt;<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>&gt;</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[
Expand All @@ -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[
Expand All @@ -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>

Expand Down