RST formatting fixes.

docs/source/development.rst

@@ -517,13 +517,13 @@ Add a contact.
 
 Provide the JID of the contact you want to add:
 
-    .. code-block:: javascript
+.. code-block:: javascript
 
     converse.contacts.add('buddy@example.com')
 
 You may also provide the fullname. If not present, we use the jid as fullname:
 
-    .. code-block:: javascript
+.. code-block:: javascript
 
     converse.contacts.add('buddy@example.com', 'Buddy')
 
@@ -538,13 +538,13 @@ Returns an object representing a chat box.
 To return a single chat box, provide the JID of the contact you're chatting
 with in that chat box:
 
-    .. code-block:: javascript
+.. code-block:: javascript
 
     converse.chats.get('buddy@example.com')
 
 To return an array of chat boxes, provide an array of JIDs:
 
-    .. code-block:: javascript
+.. code-block:: javascript
 
     converse.chats.get(['buddy1@example.com', 'buddy2@example.com'])
 
@@ -559,13 +559,13 @@ Opens a chat box and returns an object representing a chat box.
 
 To open a single chat box, provide the JID of the contact:
 
-    .. code-block:: javascript
+.. code-block:: javascript
 
     converse.chats.open('buddy@example.com')
 
 To return an array of chat boxes, provide an array of JIDs:
 
-    .. code-block:: javascript
+.. code-block:: javascript
 
     converse.chats.open(['buddy1@example.com', 'buddy2@example.com'])
 
@@ -620,19 +620,19 @@ Similar to chats.get API
 
 To open a single multi user chat box, provide the JID of the room:
 
-    .. code-block:: javascript
+.. code-block:: javascript
 
     converse.rooms.open('group@muc.example.com')
 
 To return an array of rooms, provide an array of room JIDs:
 
-    .. code-block:: javascript
+.. code-block:: javascript
 
     converse.rooms.open(['group1@muc.example.com', 'group2@muc.example.com'])
 
 To setup a custom nickname when joining the room, provide the optional nick argument:
 
-    .. code-block:: javascript
+.. code-block:: javascript
 
     converse.rooms.open('group@muc.example.com', 'mycustomnick')
 
@@ -687,6 +687,9 @@ Example:
 
     converse.tokens.get('rid')
 
+
+.. _`listen-grouping`:
+
 The "listen" grouping
 ---------------------
 
@@ -746,62 +749,182 @@ grouping:
 Events
 ======
 
-.. note:: see also the `"listen" grouping`_ API section above.
+.. note:: see also :ref:`listen-grouping` above.
 
 Event Types
 -----------
 
 Here are the different events that are emitted:
 
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
-| Event Type                      | When is it triggered?                                                                             | Example                                                                                              |
-+=================================+===================================================================================================+======================================================================================================+
-| **callButtonClicked**           | When a call button (i.e. with class .toggle-call) on a chat box has been clicked.                 | ``converse.listen.on('callButtonClicked', function (event, connection, model) { ... });``            |
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
-| **chatBoxInitialized**          | When a chat box has been initialized. Relevant to converse-chatview.js plugin.                    | ``converse.listen.on('chatBoxInitialized', function (event, chatbox) { ... });``                     |
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
-| **chatBoxOpened**               | When a chat box has been opened. Relevant to converse-chatview.js plugin.                         | ``converse.listen.on('chatBoxOpened', function (event, chatbox) { ... });``                          |
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
-| **chatRoomOpened**              | When a chat room has been opened. Relevant to converse-chatview.js plugin.                        | ``converse.listen.on('chatRoomOpened', function (event, chatbox) { ... });``                         |
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
-| **chatBoxClosed**               | When a chat box has been closed. Relevant to converse-chatview.js plugin.                         | ``converse.listen.on('chatBoxClosed', function (event, chatbox) { ... });``                          |
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
-| **chatBoxFocused**              | When the focus has been moved to a chat box. Relevant to converse-chatview.js plugin.             | ``converse.listen.on('chatBoxFocused', function (event, chatbox) { ... });``                         |
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
-| **chatBoxToggled**              | When a chat box has been minimized or maximized. Relevant to converse-chatview.js plugin.         | ``converse.listen.on('chatBoxToggled', function (event, chatbox) { ... });``                         |
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
-| **connected**                   | After connection has been established and converse.js has got all its ducks in a row.             | ``converse.listen.on('connected', function (event) { ... });``                                       |
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
-| **contactRequest**              | Someone has requested to subscribe to your presence (i.e. to be your contact).                    | ``converse.listen.on('contactRequest', function (event, user_data) { ... });``                       |
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
-| **contactStatusChanged**        | When a chat buddy's chat status has changed.                                                      | ``converse.listen.on('contactStatusChanged', function (event, buddy) { ... });``                     |
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
-| **contactStatusMessageChanged** | When a chat buddy's custom status message has changed.                                            | ``converse.listen.on('contactStatusMessageChanged', function (event, data) { ... });``               |
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
-| **initialized**                 | Once converse.js has been initialized.                                                            | ``converse.listen.on('initialized', function (event) { ... });``                                     |
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
-| **messageSend**                 | When a message will be sent out.                                                                  | ``storage_memoryconverse.listen.on('messageSend', function (event, messageText) { ... });``          |
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
-| **noResumeableSession**         | When keepalive=true but there aren't any stored prebind tokens.                                   | ``converse.listen.on('noResumeableSession', function (event) { ... });``                             |
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
-| **reconnect**                   | After the connection has dropped. Converse.js will attempt to reconnect when not in prebind mode. | ``converse.listen.on('reconnect', function (event) { ... });``                                       |
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
-| **roomInviteSent**              | After the user has sent out a direct invitation, to a roster contact, asking them to join a room. | ``converse.listen.on('roomInvite', function (event, data) { ... });``                                |
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
-| **roomInviteReceived**          | After the user has sent out a direct invitation, to a roster contact, asking them to join a room. | ``converse.listen.on('roomInvite', function (event, data) { ... });``                                |
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
-| **roster**                      | When the roster is updated.                                                                       | ``converse.listen.on('roster', function (event, items) { ... });``                                   |
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
-| **rosterPush**                  | When the roster receives a push event from server. (i.e. New entry in your buddy list)            | ``converse.listen.on('rosterPush', function (event, items) { ... });``                               |
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
-| **statusInitialized**           | When own chat status has been initialized.                                                        | ``converse.listen.on('statusInitialized', function (event, status) { ... });``                       |
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
-| **statusChanged**               | When own chat status has changed.                                                                 | ``converse.listen.on('statusChanged', function (event, status) { ... });``                           |
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
-| **statusMessageChanged**        | When own custom status message has changed.                                                       | ``converse.listen.on('statusMessageChanged', function (event, message) { ... });``                   |
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
-| **serviceDiscovered**           | When converse.js has learned of a service provided by the XMPP server. See XEP-0030.              | ``converse.listen.on('serviceDiscovered', function (event, service) { ... });``                      |
-+---------------------------------+---------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
+callButtonClicked
+~~~~~~~~~~~~~~~~~
+
+When a call button (i.e. with class .toggle-call) on a chat box has been clicked.
+
+``converse.listen.on('callButtonClicked', function (event, connection, model) { ... });``
+
+chatBoxInitialized
+~~~~~~~~~~~~~~~~~~
+
+When a chat box has been initialized. Relevant to converse-chatview.js plugin.
+
+``converse.listen.on('chatBoxInitialized', function (event, chatbox) { ... });``
+
+chatBoxOpened
+~~~~~~~~~~~~~
+
+When a chat box has been opened. Relevant to converse-chatview.js plugin.
+
+``converse.listen.on('chatBoxOpened', function (event, chatbox) { ... });``
+
+chatRoomOpened
+~~~~~~~~~~~~~~
+
+When a chat room has been opened. Relevant to converse-chatview.js plugin.
+
+``converse.listen.on('chatRoomOpened', function (event, chatbox) { ... });``
+
+chatBoxClosed
+~~~~~~~~~~~~~
+
+When a chat box has been closed. Relevant to converse-chatview.js plugin.
+
+``converse.listen.on('chatBoxClosed', function (event, chatbox) { ... });``
+
+chatBoxFocused
+~~~~~~~~~~~~~~
+
+When the focus has been moved to a chat box. Relevant to converse-chatview.js plugin.
+
+``converse.listen.on('chatBoxFocused', function (event, chatbox) { ... });``
+
+chatBoxToggled
+~~~~~~~~~~~~~~
+
+When a chat box has been minimized or maximized. Relevant to converse-chatview.js plugin.
+
+``converse.listen.on('chatBoxToggled', function (event, chatbox) { ... });``
+
+connected
+~~~~~~~~~
+
+After connection has been established and converse.js has got all its ducks in a row.
+
+``converse.listen.on('connected', function (event) { ... });``
+
+contactRequest
+~~~~~~~~~~~~~~
+
+Someone has requested to subscribe to your presence (i.e. to be your contact).
+
+``converse.listen.on('contactRequest', function (event, user_data) { ... });``
+
+contactRemoved
+~~~~~~~~~~~~~~
+
+The user has removed a contact.
+
+``converse.listen.on('contactRemoved', function (event, data) { ... });``
+
+
+contactStatusChanged
+~~~~~~~~~~~~~~~~~~~~
+
+When a chat buddy's chat status has changed.
+
+``converse.listen.on('contactStatusChanged', function (event, buddy) { ... });``
+
+contactStatusMessageChanged
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When a chat buddy's custom status message has changed.
+
+``converse.listen.on('contactStatusMessageChanged', function (event, data) { ... });``
+
+initialized
+~~~~~~~~~~~
+
+Once converse.js has been initialized.
+
+``converse.listen.on('initialized', function (event) { ... });``
+
+messageSend
+~~~~~~~~~~~
+
+When a message will be sent out.
+
+``storage_memoryconverse.listen.on('messageSend', function (event, messageText) { ... });``
+
+noResumeableSession
+~~~~~~~~~~~~~~~~~~~
+
+When keepalive=true but there aren't any stored prebind tokens.
+
+``converse.listen.on('noResumeableSession', function (event) { ... });``
+
+reconnect
+~~~~~~~~~
+
+After the connection has dropped. Converse.js will attempt to reconnect when not in prebind mode.
+
+``converse.listen.on('reconnect', function (event) { ... });``
+
+roomInviteSent
+~~~~~~~~~~~~~~
+
+After the user has sent out a direct invitation, to a roster contact, asking them to join a room.
+
+``converse.listen.on('roomInvite', function (event, data) { ... });``
+
+roomInviteReceived
+~~~~~~~~~~~~~~~~~~
+
+After the user has sent out a direct invitation, to a roster contact, asking them to join a room.
+
+``converse.listen.on('roomInvite', function (event, data) { ... });``
+
+roster
+~~~~~~
+
+When the roster is updated.
+
+``converse.listen.on('roster', function (event, items) { ... });``
+
+rosterPush
+~~~~~~~~~~
+
+When the roster receives a push event from server. (i.e. New entry in your buddy list)
+
+``converse.listen.on('rosterPush', function (event, items) { ... });``
+
+statusInitialized
+~~~~~~~~~~~~~~~~~
+
+When own chat status has been initialized.
+
+``converse.listen.on('statusInitialized', function (event, status) { ... });``
+
+statusChanged
+~~~~~~~~~~~~~
+
+When own chat status has changed.
+
+``converse.listen.on('statusChanged', function (event, status) { ... });``
+
+statusMessageChanged
+~~~~~~~~~~~~~~~~~~~~
+
+When own custom status message has changed.
+
+``converse.listen.on('statusMessageChanged', function (event, message) { ... });``
+
+serviceDiscovered
+~~~~~~~~~~~~~~~~~
+
+When converse.js has learned of a service provided by the XMPP server. See XEP-0030.
+
+``converse.listen.on('serviceDiscovered', function (event, service) { ... });``
+
 
 
 Writing a converse.js plugin
@@ -867,7 +990,7 @@ An example plugin
         var $ = converse_api.env.jQuery,
             _ = converse_api.env._,
             moment = converse_api.env.moment;
-        
+
 
         // The following line registers your plugin.
         converse_api.plugins.add('myplugin', {
@@ -882,7 +1005,7 @@ An example plugin
                 // options that the user might have passed in via
                 // converse.initialize. These values are stored in the
                 // "user_settings" attribute.
-                
+
                 // Let's assume the user might in a custom setting, like so:
                 // converse.initialize({
                 //      "initialize_message": "My plugin has been initialized"