sat_docs: xmpp/xep-proto-jid-mention.xml comparison

comparison xmpp/xep-proto-jid-mention.xml @ 75:d944c37c36fe

xmpp (xep-proto-jid-mention): typos fixes

author	souliane <souliane@mailoo.org>
date	Sat, 16 Jan 2016 18:07:21 +0100
parents	8807a553e5bf
children	16ce0419a0e9

comparison

equal deleted inserted replaced

-:8807a553e5bf
+:d944c37c36fe
 <remark><p>First draft.</p></remark>
 </revision>
 </header>
 <section1 topic='Introduction' anchor='intro'>
-	<p>Usually mentioning somebody is done in the context of a multi-user chat: a notification is triggered when somebody's nickname is written, and it often only works when a client is online and monitoring the conversation.</p>
+	<p>Mentioning somebody is usually done in the context of a multi-user chat: a notification is triggered when somebody's nickname is written, and it often only works when a client is online and monitoring the conversation.</p>
-<p>But it is more and more common to mention people in other contexts (e.g. microblogging), and it is desirable that this works even when an entity is offline or not aware of the context. This XEP offer a simple solution to mention people in any context, online or offline and even outside of XMPP</p>
+<p>But it is more and more common to mention people in other contexts (e.g. microblogging), and it is desirable that this works even when an entity is offline or not aware of the context. This XEP offers a simple solution to mention people in any context, online or offline and even outside of XMPP.</p>
 </section1>
 <section1 topic='Requirements' anchor='reqs'>
-<p>JID mention must</p>
+<p>JID mention must:</p>
 <ul>
 <li>work online and offline</li>
 <li>work if the entity is not aware of the context</li>
 <li>work outside of XMPP context (e.g. in a website)</li>
 <li>not be tied to a particular syntax</li>
 <li>(desirable) be easy to implement</li>
 </ul>
 </section1>
 <section1 topic='Glossary' anchor='glossary'>
 	<ul>
-		<li><strong>Mentioning entity</strong> — the entity which want to mention somebody.</li>
+		<li><strong>Mentioning entity</strong> — the entity which wants to mention somebody.</li>
 		<li><strong>Mentioned entity</strong> — the entity actually mentioned.</li>
 		<li><strong>Mentioned URI</strong> — URI where the entity is mentioned.</li>
 		<li><strong>PubSub</strong> — &xep0060;.</li>
 		<li><strong>MUC</strong> — &xep0045;.</li>
 		<li><strong>MIX</strong> — &xep0369;.</li>
 </section1>
 <section1 topic='Mentioning an entity' anchor='mention'>
 	<section2 topic='Basic syntax' anchor='base'>
 		<p>The syntax used by the software willing to mention a jid is up to the implemention. Nickname followed by "<strong>:</strong>" is commonly used in group chats like MUC or Internet Relay Chat (IRC) while "<strong>@</strong>" followed by nickname is often used with microblogging. Note that if it is not possible to associate a nickname with a jid without ambiguity, a bare jid SHOULD be used instead of a nickname.</p>
-		<p>To mention an entity, a &MESSAGE; stanza must be sent to the bare jid of the entity with a &lt;mention/&gt; elements which MUST have the <strong>'urn:xmpp:mention:0'</strong> namespace. The &lt;mention/&gt; element MUST have a 'uri' attribute which link to the context where the entity has been mentioned. This URI can be the URI of a MUC room, a PubSub node, a Jingle file (e.g. a photo where mentioned entity appears), a website, or anything which make sense. A &lt;body/&gt; element MUST be present with a human readable text indicating the mentioned URI (e.g. “You have been mentioned on xmpp:xsf@muc.xmpp.org?join”). No other elements or attributes are mandatory.</p>
+		<p>To mention an entity, a &MESSAGE; stanza must be sent to the bare jid of the entity with a &lt;mention/&gt; elements which MUST have the <strong>'urn:xmpp:mention:0'</strong> namespace. The &lt;mention/&gt; element MUST have a 'uri' attribute which links to the context where the entity has been mentioned. This URI can be the URI of a MUC room, a PubSub node, a Jingle file (e.g. a photo where mentioned entity appears), a website, or anything which makes sense. A &lt;body/&gt; element MUST be present with a human readable text indicating the mentioned URI (e.g. “You have been mentioned on xmpp:xsf@muc.xmpp.org?join”). No other elements or attributes are mandatory.</p>
 <example caption='basic mention of Juliet'><![CDATA[
 <message from='romeo@montage.net' to='juliet@capulet.lit' id='123'>
 <mention xmlns='urn:xmpp:mention:0' uri='xmpp:balcony@chat.shakespeare.lit?join' />
 <body>
 You have been mentioned on xmpp:balcony@chat.shakespeare.lit?join
 </body>
 </message>
 ]]></example>
 	</section2>
 	<section2 topic='Context parents' anchor='parents'>
-		<p>Sometime the 'uri' refers to an element which is a child of other one(s). For instance, a mentioned URI may refers to a website comment with a direct link, which is a part of a more general conversation, or PubSub URI refers to a microblog comment which is a child of an other comment, itself a child of the main item.</p>
+		<p>Sometime the 'uri' refers to an element which is a child of other one(s). For instance, a mentioned URI may refer to a website comment with a direct link, which is a part of a more general conversation, or PubSub URI refers to a microblog comment which is a child of another comment, itself a child of the main item.</p>
-		<p>In this case, it is desirable for the mentioned entity to know where is the main item, so it can understand the whole context. To deal with this, the mentioning entity MAY add a &lt;parents/&gt; element which MUST contain one or more &lt;parent/&gt; elements. Each &lt;parent/&gt; element MUST contain an 'uri' attribute with the URI of the parent. If more than one parents are specified, they MUST be put in order, from the more distant one to the last child before the one specified in the main &lt;mention/&gt; element.</p>
+		<p>In this case, it is desirable for the mentioned entity to know where is the main item, so it can understand the whole context. To deal with this, the mentioning entity MAY add a &lt;parents/&gt; element which MUST contain one or more &lt;parent/&gt; elements. Each &lt;parent/&gt; element MUST contain an 'uri' attribute with the URI of the parent. If more than one parents are specified, they MUST be put in order, from the more distant one to the last child just before the one specified in the main &lt;mention/&gt; element.</p>
 <example caption='mention of Juliet in microblog comments'><![CDATA[
 <message from='romeo@montage.net' to='juliet@capulet.lit' id='123'>
 <mention xmlns='urn:xmpp:mention:0' uri='xmpp:pubsub.montague.lit?;node=urn%3Axmpp%3Amicroblog%3A0%3Acomments%2Fdd88c9bc58886fce0049ed050df0c5f2'>
 <parents>
 <parent uri='xmpp:romeo%40montague.lit?;node=urn%3Axmpp%3Amicroblog%3A0;item=2ze57d9c-1c46-21df-830c-002143d3d2qgf' />
 </body>
 </message>
 ]]></example>
 	</section2>
 	<section2 topic='Context hint' anchor='context'>
-		<p>To help the mentioned entity understand the context, the mentioning entity MAY add a &lt;context&gt; element which include human readable text. What is inside is at the discretion of the mentioning entity, it MAY be the paragraph where the mentioning entity is mentioned, or anything useful.</p>
+		<p>To help the mentioned entity understand the context, the mentioning entity MAY add a &lt;context&gt; element which include human readable text. What is inside is at the discretion of the mentioning entity, it MAY be the paragraph where the entity is mentioned, or anything useful.</p>
 <example caption='mention with context hint'><![CDATA[
 <message from='juliet@capulet.lit' to='romeo@montage.net' id='123'>
 <mention xmlns='urn:xmpp:mention:0' uri='xmpp:balcony@chat.shakespeare.lit?join'>
 <context>
 O Romeo, Romeo! wherefore art thou Romeo?
 </body>
 </message>
 ]]></example>
 	</section2>
 	<section2 topic='Mention author' anchor='author'>
-		<p>If the mention is done outside of XMPP context (e.g.: on a website), the 'from' attribute of the message may be the jid of a server component or a bot. In this case, the mentioning entity can give informations on the real author of the mention.</p>
+		<p>If the mention is done outside of XMPP context (e.g.: on a website), the 'from' attribute of the message may be the jid of a server component or a bot. In this case, the mentioning entity can give information on the real author of the mention.</p>
 		<p>The author of the mention MAY be specified in &lt;author/&gt; element. If present, it MUST contain one or more of the following elements:</p>
 		<ul>
 			<li><em>JID</em> — the user jid, in a &lt;jid/&gt; element</li>
 			<li><em>email</em> — the user email address, in a &lt;email/&gt; element</li>
 			<li><em>Full Name</em> — the user full name, in a &lt;name/&gt; element</li>
 </body>
 </message>
 			  ]]></example>
 	  </section2>
 	<section2 topic='Mentioned part' anchor='part'>
-		<p>In some contexts, an URI may be not sufficient to locate the exact place of the mention. For instance, it may be be useful to know the exact message of a MUC room where the mention did take place. If a mentioning entity want to specify the exact part of the location where the mention happened, it MAY use a &lt;part/&gt; element. This element contains informations dependant of the mentioned URI. For now, only stanza-id is used, but later versions of this specification, or other XEPs can add new elements.</p>
+		<p>In some contexts, an URI may not be sufficient to locate the exact place of the mention. For instance, it may be useful to know the exact message of a MUC room where the mention did take place. If a mentioning entity wants to specify the exact part of the location where the mention happened, it MAY use a &lt;part/&gt; element. This element contains information dependent on the mentioned URI. For now, only stanza-id is used, but later versions of this specification, or other XEPs can add new elements.</p>
 		<p>If the mentioned URI refers to an XMPP context (e.g. a MUC room), a stanza id can be specified. To do so, the &xep0359; semantic is used: mentioning entity MAY add a &lt;stanza-id/&gt; element to the &lt;part/&gt; element as specified in XEP-0359.</p>
 <example caption='mention with context hint'><![CDATA[
 <message from='juliet@capulet.lit' to='romeo@montage.net' id='123'>
 <mention xmlns='urn:xmpp:mention:0' uri='xmpp:balcony@chat.shakespeare.lit?join'>
 <context>
 ]]></example>
 	</section2>
 </section1>
 <section1 topic='Configuration' anchor='configuration'>
-<p>a server MAY provide a way for clients to configure their notifications (e.g. send by email instead of XMPP, accept mentions only from entities in the roster). To do so, the &xep0050; is used on the well-defined command node <strong>'urn:xmpp:mention:0#configure'</strong>.</p>
+<p>A server MAY provide a way for clients to configure their notifications (e.g. send by email instead of XMPP, accept mentions only from entities in the roster). To do so, the &xep0050; is used on the well-defined command node <strong>'urn:xmpp:mention:0#configure'</strong>.</p>
 </section1>
 <section1 topic='Discovering Support' anchor='disco'>
 <section2 topic='Announce' anchor='disco_announce'>
 </query>
 </iq>
 ]]></example>
 </section2>
 <section2 topic='Configuration' anchor='disco_config'>
-		<p>A server doesn't have to announce JID mention namespace as it is a client feature, but if it offers a configuration node as specified in <link url='#configuration'>configuration section</link>, it MUST announce this fact by including a service discovery feature of "<em>urn:xmpp:mention:0#configure</em>".</p>
+		<p>A server doesn't have to announce JID mention namespace as it is a client feature, but if it offers a configuration node as specified in the <link url='#configuration'>configuration section</link>, it MUST announce this fact by including a service discovery feature of "<em>urn:xmpp:mention:0#configure</em>".</p>
 	</section2>
 </section1>
 <section1 topic='Business Rules' anchor='rules'>
 <ol>
 <li>On the other hand, if the mentioned entity is not following the conversation (i.e. it didn't joined the MUC room, or it didn't subscribed to the MIX conversation), the mentioning entity SHOULD use this XEP for the mention.</li>
 </ol>
 </section1>
 <section1 topic='Security Considerations' anchor='security'>
 <ol>
-<li>To avoid spamming (e.g. a mention of an entity redirecting to an advertisement), a server SHOULD allow a mentioned entity to black list mentioning entities, or to accept mentions only for some entities (e.g. entities in roster). See the <link url='#configuration'>configuration section</link> to see how to set it up. A client MAY offer the same kind of feature, but filtering is preferably done on server side to avoid useless traffic.</li>
+<li>To avoid spamming (e.g. a mention of an entity redirecting to an advertisement), a server SHOULD allow a mentioned entity to black list mentioning entities, or to accept mentions only from some entities (e.g. entities in roster). See the <link url='#configuration'>configuration section</link> to see how to set it up. A client MAY offer the same kind of feature, but filtering is preferably done on server side to avoid useless traffic.</li>
 <li>As a mention can link to malicious content, or a user may not want to join a context (and show its presence at the same time), a client SHOULD NOT open automatically the mentioned URI. Instead it SHOULD show a notification to the user, with context hint when available, and propose to join the context or not.</li>
 		<li>When an author is specified as explained in <link url='#author'>mention author section</link>, the elements, notably the &lt;jid&gt; element, are not checked. A malicious mentioning entity could use fake author information to fool mentioned entity. To avoid this, the mentioned entity's client SHOULD display a warning, like an icon or a message, to indicate that the author can't be checked.</li>
 </ol>
 </section1>
 <section1 topic='IANA Considerations' anchor='iana'>

Mercurial > sat_docs

comparison xmpp/xep-proto-jid-mention.xml @ 75:d944c37c36fe