moparisthebest
/
xeps
mirror of https://github.com/moparisthebest/xeps
1
0
Fork 0
Code Issues Releases Wiki Activity

XEP-0369: Fix example stanzas indentation.

This commit is contained in:
Emmanuel Gil Peyrot 2016-08-12 22:40:47 +01:00
parent 5444ba9b8f
commit 11045ab27e
1 changed files with 88 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

184
xep-0369.xml
View File

@ -192,10 +192,10 @@
<section3 topic="Subject Node" anchor="subject-node">
<p>The subject node publishes the current subject of channel. Subject history is stored in MAM. The id of each node is the current value of the channel subject. A single item is stored in this node at a time. Users subscribe to this node to receive subject updates. The following example shows the format of a item in the Subject node.</p>
<example caption="Subject Node"><![CDATA[
<items node='urn:xmpp:mix:nodes:subject'>
<item id='How to use Toads' />
</items>
]]></example>
<items node='urn:xmpp:mix:nodes:subject'>
<item id='How to use Toads' />
</items>
]]></example>
</section3>
<section3 topic="Participants Node" anchor="participants-node">
<p>Each channel participant is represented as an item of the 'urn:xmpp:mix:nodes:participants' channel node. Each item is named by the bare JID of the participant. For example 'coven+123456@mix.shakespeare.example' might name the node item associated with participant 'hag66@shakespeare.example'. The nick associated with the user is mandatory and is stored in the item.
@ -205,13 +205,13 @@
QUESTION: Is there a requirement to mandate format of nick?
</p>
<example caption="Value of Participants Node"><![CDATA[
<items node='urn:xmpp:mix:nodes:participants'>
<item id='coven+123456@mix.shakespeare.example/8765'>
<participant xmlns='urn:xmpp:mix:0'
nick='thirdwitch'/>
</item>
</items>
]]></example>
<items node='urn:xmpp:mix:nodes:participants'>
<item id='coven+123456@mix.shakespeare.example/8765'>
<participant xmlns='urn:xmpp:mix:0'
nick='thirdwitch'/>
</item>
</items>
]]></example>
</section3>
<section3 topic="JID Map Node" anchor="jid-map-node">
@ -219,13 +219,13 @@
Each item is identified by proxy bare JID, mapping to the real bare JID. This node is used to give administrator access to real JIDs and participant access to real JIDs in jid-visible channels.
In JID visible channels, all participants may subscribe to this node. In JID hidden channels, only administrators can subscribe. </p>
<example caption="Value of JID Map Node"><![CDATA[
<items node='urn:xmpp:mix:nodes:jidmap'>
<item id='coven+123456@mix.shakespeare.example'>
<participant xmlns='urn:xmpp:mix:0'
jid='hecate@mix.shakespeare.example'/>
</item>
</items>
]]></example>
<items node='urn:xmpp:mix:nodes:jidmap'>
<item id='coven+123456@mix.shakespeare.example'>
<participant xmlns='urn:xmpp:mix:0'
jid='hecate@mix.shakespeare.example'/>
</item>
</items>
]]></example>
</section3>
<section3 topic="Presence Node" anchor="presence-node">
@ -238,15 +238,15 @@
This node may be subscribed to by users using bare JID. So presence of online clients is sent to all users subscribed to this node, noting that presence is always sent using standard presence protocol.
</p>
<example caption="Value of Presence Node"><![CDATA[
<items node='urn:xmpp:mix:nodes:presence'>
<item id='coven+123456@mix.shakespeare.example/8765'>
<presence xmlns:”jabber:client">
<show>dnd</show>
<status>Making a Brew</status>
</presence>
</item>
</items>
]]></example>
<items node='urn:xmpp:mix:nodes:presence'>
<item id='coven+123456@mix.shakespeare.example/8765'>
<presence xmlns='jabber:client'>
<show>dnd</show>
<status>Making a Brew</status>
</presence>
</item>
</items>
]]></example>
</section3>
<section3 topic="Configuration Node" anchor="config-node">
@ -261,13 +261,13 @@
<p>TEMPORARY NOTE AND QUESTION: This is currently work in progress. Suggestions for other items to be included in configuration are welcome.</p>
<p>The format of the Configuration node follows &xep0004;. This allows configuration to be updated by MIX defined commands and that the results of update commands can be directly written to the PubSub node. Updates to the Configuration may use these commands or direct writing to the PubSub node.</p>
<example caption="Configuration Node"><![CDATA[
<items node='urn:xmpp:mix:nodes:config'>
<item id='2016-05-30T09:00:00'>
name='A Dark Cave'
*** TBS ****
</item>
</items>
]]></example>
<items node='urn:xmpp:mix:nodes:config'>
<item id='2016-05-30T09:00:00'
name='A Dark Cave'>
*** TBS ****
</item>
</items>
]]></example>
</section3>
<section3 topic="ACL Node" anchor="acl-node">
<p>The ACL node is closely related to the configuration node, and contains more information that will generally be more restricted as to who can access and modify. An anticipated configuration reflected in the defaults has ACL node configured so that it can be modified by channel owners and read only by channel owners and administrators. The default for the configuration node is update by owners or administrators and visibility to list members. Split of functionality has been made on the basis of this model. </p>
@ -304,12 +304,12 @@
<p>TEMPORARY NOTE: This is currently work in progress. Suggestions for other items to be included in ACL are welcome.</p>
<p>The format of the ACL node follows &xep0004;. </p>
<example caption="ACL Node"><![CDATA[
<items node='urn:xmpp:mix:nodes:acl'>
<item id='2016-05-30T09:00:00'>
*** TBS ****
</item>
</items>
]]></example>
<items node='urn:xmpp:mix:nodes:acl'>
<item id='2016-05-30T09:00:00'>
*** TBS ****
</item>
</items>
]]></example>
@ -376,7 +376,7 @@
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
]]></example>
<p>The channel MUST return its identity and the features it supports:</p>
<example caption='Channel Returns Disco Info Result'><![CDATA[
<iq from='coven@mix.shakespeare.lit'
@ -391,7 +391,7 @@
<feature var='urn:xmpp:mix:0'/>
</query>
</iq>
]]></example>
]]></example>
</section2>
<section2 topic='Discovering Nodes at a Channel' anchor='disco-channel-nodes'>
<p>Use disco#items to find the nodes associated with a channel. The MIX server MUST only return nodes that exist and that the user making the query has rights to subscribe to.</p>
@ -402,7 +402,7 @@
type='get'>
<query xmlns='http://jabber.org/protocol/disco#items'/>
</iq>
]]></example>
]]></example>
<example caption='Room Returns Disco Items Result'><![CDATA[
<iq from='coven@mix.shakespeare.lit'
id='kl2fax27'
@ -421,7 +421,7 @@
node='urn:xmpp:mix:nodes:config'/>
</query>
</iq>
]]></example>
]]></example>
</section2>
<section2 topic='Discovering Participants in a Channel' anchor='disco-channel-participants'>
<p>
@ -466,7 +466,7 @@
<subscribe node='urn:xmpp:mix:nodes:config'/>
</join>
</iq>
]]></example>
]]></example>
<p>As noted, the participant might not be subscribed to all nodes associated with the channel (in this case only messages, participants, and subject).</p>
<example caption="Channel Processes Join With Modifications"><![CDATA[
<iq type='result'
@ -479,7 +479,7 @@
<subscribe node='urn:xmpp:mix:nodes:subject'/>
</join>
</iq>
]]></example>
]]></example>
<p>The channel also adds the user to the participants node and sends a notification.</p>
<example caption="Channel Adds User to Participants Node"><![CDATA[
<message from='coven@mix.shakespeare.example'
@ -494,7 +494,7 @@
</items>
</event>
</message>
]]></example>
]]></example>
<p>The user that has been added to the channel is identified by the item id of the item added to the pubsub node, which is the proxy JID of the new channel participant. Each &lt;participant&gt; element will include the nick of the user being added, which will be how the user will typically be shown in the channel.</p>
<p>
Following the MIX server side processing, the user's server will usually add the MIX channel to the user's roster using one way presence. This means that the MIX channel will get presence information from the user. This roster entry will lead to correct handling of the user's presence in the MIX channel. If the user does not wish to publish presence and the channel permits this, then this roster addition does not happen. If the channel requires presence and the user removes the channel from the user's roster, the channel MAY remove the user as a channel participant.
@ -523,14 +523,14 @@
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
<leave xmlns='urn:xmpp:mix:0'/>
</iq>
]]></example>
]]></example>
<p>When the user leaves the channel, the MIX service is responsible for unsubscribing the user from all nodes in the channel and for removing the user from the participants and presence list. If the user has online presence when the user leaves the channel, the change of presence status caused by removing the user's entry or entries from the presence node will ensure that subscribers to the presence node are correctly updated on presence status.
Deletion from the participants and presence functions as if the item (channel member) had been deleted using the PubSub retract mechanism with notification set to true. Notification of the deletion is sent to clients subscribed to the participants PubSub nodes, as shown in the example below.
</p>
<example caption="Reporting when User Leaves a Channel"><![CDATA[
<message from='coven@mix.shakespeare.example' to='hecate@shakespeare.example' id='foo'>
<message from='coven@mix.shakespeare.example' to='hecate@shakespeare.example' id='foo'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='urn:xmpp:mix:nodes:participants'>
<retract id='123456@mix.shakespeare.example'/>
@ -538,14 +538,14 @@
</event>
</message>
<message from='coven@mix.shakespeare.example' to='hecate@shakespeare.example' id='bar'>
<message from='coven@mix.shakespeare.example' to='hecate@shakespeare.example' id='bar'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='urn:xmpp:mix:nodes:presence'>
<retract id='123456@mix.shakespeare.example/8765'/>
</items>
</event>
</message>
]]></example>
]]></example>
</section3>
@ -572,7 +572,7 @@
<nick>thirdwitch</nick>
</query>
</iq>
]]></example>
]]></example>
<p>
The channel will return the nick that is to be used, noting that this may be different to the requested nick. MIX services SHOULD apply the "nickname" profile of the PRECIS OpaqueString class, which is defined in draft-ietf-precis-nickname.
@ -587,7 +587,7 @@
<nick>thirdwitch</nick>
</query>
</iq>
]]></example>
]]></example>
<section3 topic='Registering a Nick' anchor='usecase-user-register'>
<p>A user can register a nick with the MIX service. Nick registration can be used ensure that a user is able to use the same nick in all channels in the service and to prevent other users from using a registered nick. This can help achieve a consistent experience across a set of channels and prevent user confusion. Support for nick registration by a MIX service is optional. Where nick registration is supported, nick registration may be optional or mandatory.
Where a user has registered a Nick with the MIX service, it may be used by each channel according to policy for the channel. A Nick is associated with the user's bare JID.
@ -602,7 +602,7 @@
id='7nve413p'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
]]></example>
<p>
The response will be a list of features of the MIX channel. If Nick Registration is supported, then the result set will include &lt;feature var="mix_nick_register"/&gt;.
</p>
@ -618,7 +618,7 @@
<nick>thirdwitch</nick>
</register>
</iq>
]]></example>
]]></example>
<p>On success, the service informs the user of its nick. The nick that is issued might be different from the nick that was requested, for example if the service completes normalization of nicknames for purposes of internationalization.</p>
<p>MIX services SHOULD apply the "nickname" profile of the PRECIS OpaqueString class, which is defined in draft-ietf-precis-nickname.</p>
<example caption="Service Returns User of Nick"><![CDATA[
@ -630,7 +630,7 @@
<nick>thirdwitch</nick>
</register>
</iq>
]]></example>
]]></example>
<p>If the requested nick is already taken, the MIX service returns a &lt;conflict/&gt; error:</p>
<example caption="Nick is Taken"><![CDATA[
<iq type='error'
@ -644,7 +644,7 @@
<conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
]]></example>
<p>If the register request does not contain a &lt;nick/&gt; element, then the MIX service assigns one. It is recommended that the assigned nick is a UUID unique identifier following &rfc4122;.
</p>
@ -669,24 +669,21 @@
<p>
A user setting status is now used as an example. Unlike in &xep0045; where coming online is a special action, coming online in MIX is implicit when presence status is set. Going offline is a achieved by setting presence status to unavailable, which removes the client full JID entry from the presence node. When a user sets a presence status, the user's server sends updated presence to the MIX channel, and the MIX server then publishes the user's availability to the "urn:xmpp:mix:nodes:presence" node. If there is not an item named by the full JID of the client with updated presence status, this item is created. If there is not an item named by the full JID of the client with updated presence status, then an item is created.</p>
<example caption="User Setting Presence Status"><![CDATA[
<presence xmlns='jabber:client' from=‘hag66@shakespeare.example/pda’ to='coven@mix.shakespeare.example'>
<show>dnd</show>
<status>Making a Brew</status>
</presence>
]]></example>
<presence xmlns='jabber:client' from=‘hag66@shakespeare.example/pda’ to='coven@mix.shakespeare.example'>
<show>dnd</show>
<status>Making a Brew</status>
</presence>
]]></example>
<p>The user's presence information is then published by the service to the "urn:xmpp:mix:nodes:presence" node, with the 'publisher' attribute set to the user's participant identifier (the proxy JID. The MIX channel then broadcasts the presence change to all users who are subscribed to the "urn:xmpp:mix:nodes:presence" node. The presence message is sent from the proxy (anonymized) full JID of the user. </p>
<example caption="Channel Distributes Presence"><![CDATA[
<presence from='coven+123435@mix.shakespeare.example/678'
to='coven@mix.shakespeare.example'
id='77E07BB0-55CF-4BD4-890E-3F7C0E686BBD'>
<nick xmlns='http://jabber.org/protocol/nick'>thirdwitch</nick>
<show>dnd</show>
<status>Making a Brew</status>
</presence>
]]></example>
to='coven@mix.shakespeare.example'
id='77E07BB0-55CF-4BD4-890E-3F7C0E686BBD'>
<nick xmlns='http://jabber.org/protocol/nick'>thirdwitch</nick>
<show>dnd</show>
<status>Making a Brew</status>
</presence>
]]></example>
<p>
The presence is distributed to those subscribing to the MIX channel presence node using a standard XMPP presence message. The presence change is recorded on the "urn:xmpp:mix:nodes:presence" node in the item for the full JID of the client to which the presence relates. The history of this node will be held as PubSub format in the MAM archive, so that presence history may be viewed.
</p>
@ -725,18 +722,16 @@
<p>When a client goes offline, this presence update is sent by the client's server to the MIX channel. From the client perspective, this is the same as any other presence change. Handling by the MIX channel is slightly different.</p>
<example caption="Client Goes Offline in the Channel"><![CDATA[
<presence type='unavailable'
from='hag66@shakespeare.example/pda'
to='coven@mix.shakespeare.example'/>
]]></example>
from='hag66@shakespeare.example/pda'
to='coven@mix.shakespeare.example'/>
]]></example>
<p>The MIX channel will retract (remove) the item in the presence node of the MIX channel identified by the client's full JID. The MIX channel will notify subscribers to the presence node of the user going offline using a presence message from the proxy JID of the client.</p>
<example caption="Channel Distributes Notification of Client going Offline"><![CDATA[
<presence from='coven+12345@mix.shakespeare.example/678'
to='hecate@shakespeare.example'
id='77E07BB0-55CF-4BD4-890E-3F7C0E686BBD'>
type=unavailable
</presence>
]]></example>
to='hecate@shakespeare.example'
id='77E07BB0-55CF-4BD4-890E-3F7C0E686BBD'
type='unavailable'/>
]]></example>
<p>
There is the possibility that the message associated with the user going offline will be lost. If this happens, "ghost" entries will appear in the presence node. A MIX server may take steps to address this, for example by probing client with a disco for presence items that remain unchanged for a long period.
@ -751,23 +746,22 @@
<section3 topic='Sending a Message' anchor='usecase-user-message'>
<p>A user sends a message to a MIX channel as a standard groupchat message, in exactly the same way as for &xep0045;. </p>
<example caption="User Sends Message to Channel"><![CDATA[
<message
from='hag66@shakespeare.example/pda'
to='coven@mix.shakespeare.example'
id='92vax143g'
type=groupchat>
<body>Harpier cries: 'tis time, 'tis time.</body>
</message>
]]></example>
<message from='hag66@shakespeare.example/pda'
to='coven@mix.shakespeare.example'
id='92vax143g'
type='groupchat'>
<body>Harpier cries: 'tis time, 'tis time.</body>
</message>
]]></example>
<p>The message comes from the channel as a pubsub notification, with the 'publisher' attribute set to the participant identifier of the sender.</p>
<example caption="Channel Reflects Message to Participants"><![CDATA[
<message from='coven+12345@mix.shakespeare.example/678'
to='hecate@shakespeare.example'
id='77E07BB0-55CF-4BD4-890E-3F7C0E686BBD'
type=groupchat>
<body>Harpier cries: 'tis time, 'tis time.</body>
type='groupchat'>
<body>Harpier cries: 'tis time, 'tis time.</body>
</message>
]]></example>
]]></example>
</section3>
<section3 topic="Retracting a Message" anchor="usecase-retract">
@ -850,14 +844,12 @@
AUTHOR'S NOTE: Dave Cridland has suggested the following protocol.
<![CDATA[
<iq to='mix.cridland.im' type='set'>
<iq to='mix.cridland.im' type='set'>
<create channel='some-room-here@mix.cridland.im' xmlns='urn:xmpp:mix:0'>
<optional-configuration-form/>
</create>
</iq>
]]>
]]>
</p>
<example caption="" ><![CDATA[