Various documentation improvements.

docs/source/features.rst

@@ -63,13 +63,10 @@ Languages increase the size of the Converse.js significantly.
 If you only need one, or a subset of the available languages, it's better to
 make a custom build which includes only those languages that you need.
 
-Chat Rooms
-==========
+Moderating chat rooms
+=====================
 
-Commands
---------
-
-Here are the different commands that may be used in a chat room:
+Here are the different commands that may be used to moderate a chat room:
 
 +------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
 | Event Type | When is it triggered?                                                                        | Example (substitue $nickname with an actual user's nickname)  |

docs/source/plugin_development.rst

@@ -22,7 +22,7 @@ its plugin architecture.
 
 To understand how this plugin architecture works, please read the
 `pluggable.js documentation <https://jcbrand.github.io/pluggable.js/>`_
-and to grok its inner workins, please refer to the `annotated source code
+and to understand its inner workins, please refer to the `annotated source code
 <https://jcbrand.github.io/pluggable.js/docs/pluggable.html>`_.
 
 You register a converse.js plugin as follows:
@@ -30,7 +30,15 @@ You register a converse.js plugin as follows:
 .. code-block:: javascript
 
     converse.plugins.add('myplugin', {
-        // Your plugin code goes in here
+
+        initialize: function () {
+            // This method gets called once converse.initialize has been called
+            // and the plugin itself has been loaded.
+
+            // Inside this method, you have access to the closured
+            // _converse object as an attribute on "this".
+            // E.g. this._converse
+        },
     });
 
 Security and access to the inner workings
@@ -47,13 +55,29 @@ Within a plugin, you will have access to this internal
 `"closured" <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Closures>`_
 ``_converse`` object, which is normally not exposed in the global variable scope.
 
-We inner ``_converse`` object is made private in order to safely hide and
+The inner ``_converse`` object is made private in order to safely hide and
 encapsulate sensitive information and methods which should not be exposed
 to any 3rd-party scripts that might be running in the same page.
 
 An example plugin
 -----------------
 
+In the example below, you can see how to access 3rd party libraries (such
+moment, underscore and jQuery) via the ``converse.env`` map.
+
+There is an ``initialize`` method as you've seen in the example above, and then
+also an ``overrides`` map, which can be used to override functions, objects or
+Backbone views and models of Converse.js.
+
+Use the ``overrides`` functionality with caution. It basically resorts to
+monkey patching which pollutes the call stack and can make your code fragile
+and prone to bugs when Converse.js gets updated. Too much use of ``overrides``
+is therefore a "code smell" which should ideally be avoided.
+
+A better approach is to listen to the events emitted by Converse.js, and to add
+your code in event handlers. This is however not always possible, in which case
+the overrides are a powerful tool.
+
 .. code-block:: javascript
 
     (function (root, factory) {

docs/source/quickstart.rst

@@ -2,9 +2,15 @@
 
     <div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/quickstart.rst">Edit me on GitHub</a></div>
 
-=========================================
-Quickstart (to get a demo up and running)
-=========================================
+==========
+Quickstart
+==========
+
+Getting a demo up and running
+=============================
+
+Use the content delivery network
+--------------------------------
 
 Converse.js has a `CDN <https://en.wikipedia.org/wiki/Content_delivery_network>`_, provided by `KeyCDN <http://keycdn.com/>`_,
 which hosts its Javascript and CSS files.
@@ -14,7 +20,7 @@ The latest versions of these files are available at these URLs:
 * https://cdn.conversejs.org/dist/converse.min.js
 * https://cdn.conversejs.org/css/converse.min.css
 
-For a specific version of the files, you can put the version in the URL, as so:
+To load a specific version of Converse.js you can put the version in the URL, like so:
 
 * https://cdn.conversejs.org/1.0.3/dist/converse.min.js
 * https://cdn.conversejs.org/1.0.3/css/converse.min.css
@@ -26,12 +32,14 @@ You can include these two URLs inside the *<head>* element of your website via t
     <link rel="stylesheet" type="text/css" media="screen" href="https://cdn.conversejs.org/css/converse.min.css">
     <script src="https://cdn.conversejs.org/dist/converse.min.js"></script>
 
-You need to initialize Converse.js with configuration settings according to your requirements.
+Initializing Converse.js
+------------------------
 
-Please refer to the :ref:`configuration-variables` section for info on all the available configuration settings.
+You'll then need to initialize Converse.js with configuration settings relevant to your requirements.
+Refer to the :ref:`configuration-variables` section for info on all the available configuration settings.
 
-To configure and initialize Converse.js, put the following inline Javascript code at the
-bottom of your page (after the closing *</body>* element).
+To quickly get started, you can put the following Javascript code at the
+bottom of your page (after the closing *</body>* element):
 
 .. code-block:: javascript
 
@@ -39,9 +47,7 @@ bottom of your page (after the closing *</body>* element).
     require(['converse'], function (converse) {
         converse.initialize({
             bosh_service_url: 'https://bind.conversejs.org', // Please use this connection manager only for testing purposes
-            i18n: locales.en, // Refer to ./locale/locales.js to see which locales are supported
             show_controlbox_by_default: true,
-            roster_groups: true
         });
     });
     </script>
@@ -49,14 +55,51 @@ bottom of your page (after the closing *</body>* element).
 The `index.html <https://github.com/jcbrand/converse.js/blob/master/index.html>`_ file inside the
 Converse.js repository may serve as a nice usable example.
 
-These minified `.js` and `.css` files provide the same demo-like functionality as is available
+Alternative builds of Converse.js
+=================================
+
+The minified ``.js`` and ``.css`` files provide the same functionality as is available
 on the `conversejs.org <http://conversejs.org>`_ website. Useful for testing or demoing.
 
-You'll most likely want to implement some kind of persistent single-session solution for
-your website, where users authenticate once in your website and then stay
-logged in to their XMPP session upon the next page reload.
+Alternative builds are however also available via the CDN.
+
+Mobile build
+------------
+
+Besides the default build mentioned above, there is a build intended for mobile
+websites, called ``converse-mobile.min.js``.
+Take a look at the ``mobile.html`` file in the Converse.js repository
+for an example of this build being used. There's an additional CSS file called 
+``mobile.min.css`` which should be used with the mobile build.
+
+When you load `conversejs.org <https://conversejs.org>`_ with a mobile device
+then the mobile Javascript build and its CSS will be used.
+
+Excluding 3rd party dependencies
+--------------------------------
+
+Then there is also a build that contains no 3rd party dependencies, called 
+``converse-no-dependencies.min.js`` and which is used in the ``non_amd.html``
+page in the repository.
+
+Excluding only jQuery
+---------------------
+
+Lastly there is a build called ``converse.nojquery.min.js`` which excludes only
+jQuery but still includes all other 3rd party dependencies.
+
+Where to go from here?
+======================
+
+You might want to implement some kind of persistent single-session solution for
+your website, where users authenticate once in your website and are then
+automatically logged in to the XMPP server as well. For more info on how this
+can be achieved, read: :ref:`session-support`.
+
+Perhaps you want to create your own custom build of Converse.js? Then head over
+to the :doc:`builds` section, or more generally the :doc:`development`
+documentation.
 
-For more info on this, read: :ref:`session-support`.
+Do you want to know how to theme Converse.js? Then read the :doc:`theming`
+documentation.
 
-You might also want to have more fine-grained control of what gets included in
-the minified Javascript file. Read :doc:`builds` for more info on how to do that.

docs/source/theming.rst

@@ -2,6 +2,8 @@
 
     <div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div>
 
+.. _theming:
+
 =======
 Theming
 =======