xep-0058.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM "xep.ent">
%ents;
]>
<?xml-stylesheet type="text/xsl" href="xep.xsl"?>
<xep>
  <header>
    <title>Multi-User Text Editing</title>
    <abstract>This document defines how several people may simultaneously edit text.</abstract>
    &LEGALNOTICE;
    <number>0058</number>
    <status>Deferred</status>
    <type>Standards Track</type>
    <sig>Standards</sig>
    <approver>Council</approver>
    <dependencies/>
    <supersedes/>
    <supersededby/>
    <shortname>N/A</shortname>
    <author>
      <firstname>Alexey</firstname>
      <surname>Shchepin</surname>
      <email>alexey@sevcom.net</email>
      <jid>aleksey@jabber.ru</jid>
    </author>
    <revision>
      <version>0.1</version>
      <date>2002-11-12</date>
      <initials>as</initials>
      <remark>Initial version.</remark>
    </revision>
  </header>

  <section1 topic="Introduction">
    <p>
      This document defines an XMPP protocol extension for editing one text
      document by several people.
      This can be useful when several people write different parts of one single
      document, or one person edits the text and other people can see the
      changes.
      The advantage of using this protocol in compared to using a  version
      control systems is that all changes are distributed between editors in
      real-time.
    </p>
  </section1>

  <section1 topic="Protocol description">
    <p>
      To start editing a file, the user must subscribe to it on special "server"
      The server stores text files.  A User first can ask for list of these documents.
    </p>
    <example caption="User asks the server list of editable texts"><![CDATA[<iq type='get' to='server' id='mute1'>
  <list xmlns='http://jabber.org/protocol/mute#server'/>
</iq>]]></example>
    <p>
      After that the server returns a list of the documents.  For each list
      item an ID and description is given.
    </p>
    <example caption="Ancestor returns list of editable texts"><![CDATA[<iq type='result' to='editor1' id='mute1'>
  <list xmlns='http://jabber.org/protocol/mute#server'>
    <item id='id1' desc='Useful text'/>
    <item id='id2' desc='Useless text'/>
  </list>
</iq>]]></example>
    <p>
      Then the user can send a subscribe request to the server by sending the documents ID.
      Attribute <tt>type</tt> can be <tt>rdwr</tt> for full access or
      <tt>rdonly</tt> for read-only access.
    </p>
    <example caption="User sends subscribe request"><![CDATA[<iq type='set' to='server' id='mute2'>
  <subscribe xmlns='http://jabber.org/protocol/mute#server'>
    <item id='id1' type='rdwr'/>
  </subscribe>
</iq>]]></example>
    <example caption="Positive response from server on subscribe
	     request"><![CDATA[<iq type='result' to='editor1' id='mute2'/>]]></example>
    <example caption="Negative response from server on subscribe
	     request"><![CDATA[<iq type='error' to='editor1' id='mute2'>
  <subscribe xmlns='http://jabber.org/protocol/mute#server'>
    <item id='id1' type='rdwr'/>
  </subscribe>
  <error code="405">Not Allowed</error>
</iq>]]></example>
    <p>
      After successful subscription, the server sends the full contents of the document to
      the new editor.
    </p>
    <example caption="Server sends text to editor"><![CDATA[<iq type='set' to='editor1' id='mute3'>
  <text xmlns='http://jabber.org/protocol/mute#editor' id='id1'>
...
8. Admin Use Cases
   8.1. Banning a User
   8.2. Modifying the Ban List
   8.3. Granting Membership
   8.4. Revoking Mambership
   8.5. Modifying the Member List
   8.6. Granting Moderator Privileges
   8.7. Revoking Moderator Privileges
   8.8. Modifying the Moderator List
...
  </text>
</iq>]]></example>
    <example caption="Positive response from editor"><![CDATA[<iq type='result' to='server' id='mute3'/>]]></example>
    <p>
      If an editor wants to commit the changes he made, then he sends a  patch file to this text
      in GNU diff(1) unified format without first two lines (they specify file
      names and modification dates, that is not needed).
    </p>
    <example caption="Editor sends patch to server"><![CDATA[<iq type='set' to='server' id='mute4'>
  <patch xmlns='http://jabber.org/protocol/mute#server' id='id1'>
@@ -2,7 +2,7 @@
    8.1. Banning a User
    8.2. Modifying the Ban List
    8.3. Granting Membership
-   8.4. Revoking Mambership
+   8.4. Revoking Membership
    8.5. Modifying the Member List
    8.6. Granting Moderator Privileges
    8.7. Revoking Moderator Privileges
  </patch>
</iq>]]></example>
    <example caption="Server accepts patch"><![CDATA[<iq type='result' to='editor1' id='mute4'/>]]></example>
    <example caption="Server not accepts patch"><![CDATA[<iq type='error' to='editor1' id='mute4'>
  <patch xmlns='http://jabber.org/protocol/mute#server' id='id1'>
@@ -2,7 +2,7 @@
    8.1. Banning a User
    8.2. Modifying the Ban List
    8.3. Granting Membership
-   8.4. Revoking Mambership
+   8.4. Revoking Membership
    8.5. Modifying the Member List
    8.6. Granting Moderator Privileges
    8.7. Revoking Moderator Privileges
  </patch>
  <error code="405">Not Allowed</error>
</iq>]]></example>
    <p>
      If server accepts the patch, then it resends it to all subscribed text editors and readers.
    </p>
    <example caption="Server resend accepted patch to all editors and readers
	     of this text"><![CDATA[<iq type='set' to='editor1' id='mute5'>
  <patch xmlns='http://jabber.org/protocol/mute#editor' id='id1'>
@@ -2,7 +2,7 @@
    8.1. Banning a User
    8.2. Modifying the Ban List
    8.3. Granting Membership
-   8.4. Revoking Mambership
+   8.4. Revoking Membership
    8.5. Modifying the Member List
    8.6. Granting Moderator Privileges
    8.7. Revoking Moderator Privileges
  </patch>
</iq>]]></example>
    <example caption="Positive response from editors and readers"><![CDATA[<iq type='result' to='server' id='mute5'/>]]></example>

    <p>
      If server receives an  error IQ reply from one of the editors/readers on any of
      above requests, then it must remove him from subscribers list and may
      send a message to him about this.
    </p>

  </section1>

  <section1 topic="Formal Definitions">
    <example caption="DTD for http://jabber.org/protocol/mute#server"><![CDATA[<?xml version="1.0" encoding="UTF-8" ?>

<!ELEMENT list ((item)*)>
<!ELEMENT subscribe (item)>

<!ELEMENT item EMPTY>
<!ATTLIST item
          id CDATA #REQUIRED
          desc CDATA #IMPLIED
          type ( rdwr | rdonly ) #IMPLIED >

<!ELEMENT patch (#PCDATA)>]]></example>
    <example caption="DTD for http://jabber.org/protocol/mute#editor"><![CDATA[<?xml version="1.0" encoding="UTF-8" ?>

<!ELEMENT patch (#PCDATA)>
<!ELEMENT text (#PCDATA)>]]></example>
  </section1>
</xep>