Update the developer documentation

docs/source/api/index.rst

@@ -2,9 +2,9 @@
 
     <div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div>
 
-=====================
-The API documentation
-=====================
+============================================
+The API documentation (generated with JSDoc)
+============================================
 
 This document is a stub. It shouldn't show at all, instead it's a hack in order
 to link to the JSDoc output.

docs/source/builds.rst

@@ -5,9 +5,9 @@
 
 .. _builds:
 
-===============
-Creating builds
-===============
+=================
+Generating builds
+=================
 
 .. contents:: Table of Contents
    :depth: 3
@@ -15,72 +15,65 @@ Creating builds
 
 
 .. warning:: There current documentation in this section does not adequately
-    explain how to create custom builds.
+    explain how to create custom bundles.
 
-.. note:: Please make sure to read the section :doc:`development` and that you have installed
+.. Note:: Please make sure to read the section :doc:`development` and that you have installed
     all development dependencies (long story short, you should be able to just run  ``make dev``)
 
-Creating builds and distribution files
-======================================
+Creating JavaScript and CSS bundles and distribution files
+==========================================================
 
-Converse.js uses `AMD (Asynchronous Modules Definition) <http://requirejs.org/docs/whyamd.html#amd>`_
-to define modules and their dependencies.
+Converse uses `webpack <https://webpack.js.org/>`_ to create single build files containing the core code and
+all of the 3rd party dependencies.
 
-Dependencies can then be loaded on-the-fly with `require.js <http://requirejs.org>`_.
-This is very useful during development, but when it comes to
-deployement you'll usually want to create a single, minified distribution build.
+These files are in the `dist <https://github.com/conversejs/converse.js/tree/master/dist>`_ directory.
 
-For this, the `r.js optimizer <http://requirejs.org/docs/optimization.html>`_
-is used together with `almond.js <https://github.com/requirejs/almond>`_, which
-is a smaller and minimal AMD API implementation that replaces require.js in builds.
+Before you start changing the core code, you can run ``make watchjs`` in your terminal.
 
-To create the distribution builds, simply run::
+This command will listen for any changed files and then automatically create a
+new build of ``dist/converse.js``.
 
-    make dist
-
-This command does the following:
+The CSS files are also generated, from the scss files in the
+`sass <https://github.com/conversejs/converse.js/tree/master/sass>`_ directory.
 
-* It creates different builds of Converse.js in the ``./dist/`` directory.
+Similarly to ``make watchjs``, you can run ``make watch`` to automatically
+generate the css files in the ``./css/`` directory.
 
-* It bundles all the translation files in ``./locale/`` into a single file ``locales.js``.
-  This file can then be included via the ``<script>`` tag. See for example the ``non_amd.html`` example page.
+The Converse repository does not include the minified files in the ``dist`` or
+``css`` directories. Before deployment, you'll want to generate them yourself.
 
-* Also, the CSS files in the ``./css`` directory will be minified.
+To do so, run the following:
 
-The JavaScript build files are contained in the ``./dist`` directory:
+::
+    make dist/converse.min.js
+    make css/converse.min.css
 
-.. code-block:: bash
+Alternatively, if you want to generate ALL the bundles files (minified and
+unminified), then you can also run::
 
-    jc@conversejs:~/converse.js (master)$ ls dist/
-    converse-mobile.js               converse.min.js
-    converse-mobile.min.js           converse.nojquery.js
-    converse-no-dependencies.js      converse.nojquery.min.js
-    converse-no-dependencies.min.js  locales.js
-    converse.js
+    make dist
 
-.. _`minification`:
 
-Creating custom builds
-----------------------
+Creating custom bundles
+=======================
 
-One reason you might want to create your own builds, is because you want to
-remove some of the core plugins of converse.js, or perhaps you want to include
+One reason you might want to create your own bundles, is because you want to
+remove some of the core plugins of Converse, or perhaps you want to include
 your own.
 
 To add or remove plugins from the build, you need to modify the
-``src/converse.js`` file.
+`src/converse.js <https://github.com/conversejs/converse.js/blob/master/src/converse.js>`_ file.
 
 You'll find a section marked ``/* START: Removable components`` and
 ``/* END: Removable components */``.
 
-In this section is listed all the converse.js plugins that will make up a
-build.
+In this section is listed the Converse plugins that will make up a bundle.
 
 You could for example decide to disable the ControlBox altogether by removing
 the ``converse-controlbox`` plugin.
 
 After doing so, you need to run ``make dist`` again in the root or your
-converse.js repository, in order to generate the new build.
+Converse repository, in order to generate the new build.
 
 Be aware that some plugins might have dependencies on other plugins, so if you
 remove a certain plugin but other included plugins still depend on it, then it
@@ -91,12 +84,35 @@ text editor and look at the list specified as the second parameter to the
 ``define`` call, near the top of the file. This list specifies the dependencies
 of that plugin.
 
-Minifying the CSS
------------------
+Besides the standard build, the Converse repository includes configuration
+for certain other non-standard builds, which we'll now mention below.
+
+Excluding all 3rd party dependencies
+------------------------------------
+
+The ``dist/converse-no-dependencies.js`` bundle contains only the core Converse
+code and none of the 3rd party dependencies. This might be useful if you need
+to load the dependencies separately.
+
+To generate this bundle, you can run:
+
+::
+
+    make dist/converse-no-dependencies.js
+    make dist/converse-no-dependencies.min.js
+
+Headless build
+--------------
 
-To only minify the CSS files, nothing else, run the following command::
+There is also the option of making a headless build of Converse.
 
-    make cssmin
+This is a build without any UI code but still containing the core functionality of
+maintaining a roster, chats and messages.
 
-The CSS files  are minified via `cssmin <https://github.com/gruntjs/grunt-contrib-cssmin>`_.
+The file `src/headless.js <https://github.com/jcbrand/converse.js/blob/master/src/headless.js>`_
+is used to determine which plugins are included in the build.
 
+.. Note:: Unfortunately it's currently not yet possible to include Multi-user chat (MUC)
+    functionality in the headless build. This is because both the UI and core
+    functionality is still contained in one plugin and would first need to be
+    split up into two parts, with the UI part dropped for this build.

docs/source/dependencies.rst

@@ -0,0 +1,118 @@
+.. raw:: html
+
+    <div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div>
+
+============
+Dependencies
+============
+
+Installing the 3rd party dependencies
+=====================================
+
+.. note::
+    Windows environment: We recommend installing the required tools using `Chocolatey <https://chocolatey.org/>`_
+    You will need Node.js (nodejs.install), Git (git.install) and optionally to build using Makefile, GNU Make (make)
+    If you have trouble setting up a development environment on Windows,
+    please read `this post <http://librelist.com/browser//conversejs/2014/11/5/openfire-converse-and-visual-studio-questions/#b28387e7f8f126693b11598a8acbe810>`_
+    in the mailing list.:
+
+
+We use development tools which depend on Node.js and npm (the Node package manager).
+
+If you don't have Node.js installed, you can download and install the latest
+version `here <https://nodejs.org/download>`_.
+
+Alternatively you can `use your operating system's package manager to install
+Node.js <https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions>`_.
+
+Also make sure you have ``Git`` installed. `See here <http://git-scm.com/book/en/Getting-Started-Installing-Git>`_.
+
+Now use ``git`` to check out the Converse repository:
+
+::
+
+    git clone git@github.com:conversejs/converse.js.git
+
+Now go into the repository checkout and run ``make dev`` in order to set up the
+development environment.
+
+::
+    
+    cd converse.js
+    make dev
+
+On Windows you need to specify Makefile.win to be used by running:
+
+::
+
+    make -f Makefile.win dev
+
+Alternatively, if you don't have GNU Make (necessary for the ``make`` command),
+you can use NPM directly:
+
+::
+
+    npm install
+
+
+This will install the Node.js development tools and Converse's dependencies.
+
+The front-end dependencies are those JavaScript files on which
+Converse directly depends and which will be loaded in the browser as part of
+the bundle in ``dist/converse.js`` (or ``dist/converse.min.js``).
+
+To see the 3rd party dependencies (not just the front-end dependencies, but 
+also ones necessary for development tasks like making builds), take a look at
+the list under the ``devDependencies`` in `package.json <https://github.com/jcbrand/converse.js/blob/master/package.json>`_.
+
+.. note::
+    After running ```make dev```, you should now have a new *node_modules* directory
+    which contains all the external dependencies of Converse.
+    If this directory does NOT exist, something must have gone wrong.
+    Double-check the output of ```make dev``` to see if there are any errors
+    listed. For support, you can ask in our chatroom: `dicuss@conference.conversejs.org <xmpp:discuss@conference.conversejs.org>`_.
+
+    If you don't have an XMPP client installed, follow this link to
+    `conversejs.org <https://conversejs.org/fullscreen#converse/room?jid=discuss@conference.conversejs.org>`_
+    where you can log in and be taken directly to the chatroom.
+
+
+Brief description of Converse's dependencies
+===============================================
+
+Converse relies on the following dependencies:
+
+* `moment.js <http://momentjs.com/>`_ provides a better API for handling dates and times.
+* `Strophe.js <http://strophe.im/>`_ maintains the XMPP session, is used to
+  build XMPP stanzas, to send them, and to register handlers for received stanzas.
+* `lodash <https://lodash.com/>`_ provides very useful utility functions.
+* `Backbone <http://backbonejs.org/>`_ is used to model the data as Models and
+  Collections and to create Views that render the UI.
+* `backbone.overview <http://github.com/jcbrand/backbone.overview>`_ provides
+  ``Backbone.Overview``, which is to Views as Backbone Collection is to Models.
+  It also provides the ``Backbone.OrderedListView`` which is used to show
+  alphabetically sorted lists, such as your contacts roster.
+* `backbone.vdomview <http://github.com/jcbrand/backbone.vdomview>`_ provides
+  ``Backbone.VDOMView`` that uses the `Snabbdom <https://github.com/snabbdom/snabbdom>`_ 
+  virtual DOM for rendering DOM elements.
+* `pluggable.js <https://github.com/jcbrand/pluggable.js>`_ provides the plugin
+  architecture for Converse. It registers and initializes plugins and
+  allows existing attributes, functions and objects on Converse to be
+  overridden inside plugins.
+
+Libsignal
+---------
+
+Optionally, if you want OMEMO encryption, you need to load `libsignal
+<https://github.com/signalapp/libsignal-protocol-javascript>`_ separately in
+your page.
+
+For example::
+
+    <script src="3rdparty/libsignal-protocol-javascript/dist/libsignal-protocol.js"></script>
+
+The reason libsignal needs to be loaded separately is because it's released
+under the `GPLv3 <https://github.com/signalapp/libsignal-protocol-javascript/blob/master/LICENSE>`_
+which requires all other dependent JavaScript code to also be open sourced under the same
+license. You might not be willing to adhere to those terms, which is why you
+need to decide for yourself whether you're going to load libsignal or not.

docs/source/developer_guidelines.rst

@@ -1,142 +0,0 @@
-.. raw:: html
-
-    <div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div>
-
-Developer guidelines
-====================
-
-If you want to work with the non-minified JavaScript and CSS files you'll soon
-notice that there are references to a missing *node_modules* directory.
-Please follow the instructions below to create these directories and fetch Converse's
-3rd-party dependencies.
-
-.. note::
-    Windows environment: We recommend installing the required tools using `Chocolatey <https://chocolatey.org/>`_
-    You will need Node.js (nodejs.install), Git (git.install) and optionally to build using Makefile, GNU Make (make)
-    If you have trouble setting up a development environment on Windows,
-    please read `this post <http://librelist.com/browser//conversejs/2014/11/5/openfire-converse-and-visual-studio-questions/#b28387e7f8f126693b11598a8acbe810>`_
-    in the mailing list.:
-
-Installing the development and front-end dependencies
------------------------------------------------------
-
-We use development tools which depend on Node.js and npm (the Node package manager).
-
-If you don't have Node.js installed, you can download and install the latest
-version `here <https://nodejs.org/download>`_.
-
-Also make sure you have ``Git`` installed. `Details <http://git-scm.com/book/en/Getting-Started-Installing-Git>`_.
-
-.. note::
-    Windows users should use Chocolatey as recommended above.
-
-.. note::
-    Debian & Ubuntu users : apt-get install git npm nodejs-legacy
-
-Once you have *Node.js* and *git* installed, run the following command inside the Converse.js
-directory:
-
-::
-
-    make dev
-
-On Windows you need to specify Makefile.win to be used by running: ::
-
-    make -f Makefile.win dev
-
-Or alternatively, if you don't have GNU Make:
-
-::
-
-    npm install
-
-This will install the Node.js development tools and Converse.js's front-end dependencies.
-
-The front-end dependencies are those javascript files on which
-Converse.js directly depends and which will be loaded in the browser.
-
-To see the dependencies, take a look at whats under the *devDependencies* key in
-    `package.json <https://github.com/jcbrand/converse.js/blob/master/package.json>`_.
-
-.. note::
-    After running ```make dev```, you should now have a new *node_modules* directory
-    which contains all the external dependencies of Converse.js.
-    If these directory does NOT exist, something must have gone wrong.
-    Double-check the output of ```make dev``` to see if there are any errors
-    listed. For support, you can write to the mailing list: conversejs@librelist.com
-
-Loading converse.js and its dependencies
-----------------------------------------
-
-With AMD and require.js (recommended)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Converse.js uses `require.js <http://requirejs.org>`_ to asynchronously load dependencies.
-
-If you want to develop or customize converse.js, you'll want to load the
-non-minified javascript files.
-
-Add the following two lines to the *<head>* section of your webpage:
-
-.. code-block:: html
-
-    <link rel="stylesheet" type="text/css" media="screen" href="converse.css">
-    <script data-main="main" src="node_modules/requirejs/require.js"></script>
-
-require.js will then let the main.js file be parsed (because of the *data-main*
-attribute on the *script* tag), which will in turn cause converse.js to be
-parsed.
-
-Without AMD and require.js
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Converse.js can also be used without require.js. If you for some reason prefer
-to use it this way, please refer to
-`non_amd.html <https://github.com/jcbrand/converse.js/blob/master/non_amd.html>`_
-for an example of how and in what order all the JavaScript files that converse.js
-depends on need to be loaded.
-
-Brief description of converse.js's dependencies
------------------------------------------------
-
-Converse.js relies on the following dependencies:
-
-* `moment.js <http://momentjs.com/>`_ provides a better API for handling dates and times.
-* `Strophe.js <http://strophe.im/>`_ maintains the XMPP session, is used to
-  build XMPP stanzas, to send them, and to register handlers for received stanzas.
-* `lodash <https://lodash.com/>`_ provides very useful utility functions.
-* `Backbone <http://backbonejs.org/>`_ is used to model the data as Models and
-  Collections and to create Views that render the UI.
-* `backbone.overview <http://github.com/jcbrand/backbone.overview>`_ provides
-  Overviews, which are to Views as Backbone Collections are to Models.
-* `pluggable.js <https://github.com/jcbrand/pluggable.js>`_ is the plugin
-  architecture for Converse.js. It registers and initializes plugins and
-  allows existing attributes, functions and objects on converse.js to be
-  overridden inside plugins.
-
-When submitting a pull request
-------------------------------
-
-Please follow the usual github workflow. Create your own local fork of this repository,
-make your changes and then submit a pull request.
-
-Follow the programming style guide
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Please read the `style guide </docs/html/style_guide.html>`_ and make sure that your code follows it.
-
-Add tests for your bugfix or feature
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Add a test for any bug fixed or feature added. We use Jasmine
-for testing.
-
-Take a look at `tests.html <https://github.com/jcbrand/converse.js/blob/master/tests.html>`_
-and the `spec files <https://github.com/jcbrand/converse.js/blob/master/tests.html>`_
-to see how tests are implemented.
-
-Check that the tests pass
-~~~~~~~~~~~~~~~~~~~~~~~~~
-Check that all tests complete sucessfully.
-
-Run ``make check`` in your terminal or open `tests.html <https://github.com/jcbrand/converse.js/blob/master/tests.html>`_
-in your browser.

docs/source/development.rst

@@ -8,21 +8,39 @@
 Development
 ===========
 
-Welcome to the developer documentation of Converse. Read the documentation
-linked to below, if you want to add new features or create your own customized
-version of Converse.
+Welcome to the developer documentation of Converse.
+
+Read the documentation linked to below, if you want to add new features or
+create your own customized version of Converse.
+
+Converse has a plugin architecture (see `pluggable.js <https://github.com/jcbrand/pluggable.js/>`_)
+which lets you add new features or modify existing functionality without having to touch
+the core files (in the `src/ <https://github.com/conversejs/converse.js/tree/master/src>`_ directory).
+This is the recommended way to customize or add new functionality to Converse.
+
+Plugins are especially useful if you want to add proprietary modifications, since the
+Mozilla Public License version 2 doesn't require you to open source your
+plugins. Be aware that this doesn't apply when you intend to use libsignal for
+OMEMO encryption because libsignal's license is GPLv3.
+
+Refer to the section on `plugin development <https://conversejs.org/docs/html/plugin_development.html>`_
+for more info on how to write plugins.
+
+Converse is a community project and largely volunteer driven.
+
+We're grateful for your contributions, so please don't hesitate to 
+make a `Github pull request <https://help.github.com/categories/collaborating-with-issues-and-pull-requests/>`_
+to fix a bug or to add new functionality.
 
-Converse itself composed of plugins, and exposes an API with which you can
-create and register your own plugins. This is the recommended way to customize
-or add new functionality to Converse.
 
 .. toctree::
    :maxdepth: 2
 
-   developer_guidelines
+   dependencies
    style_guide
    plugin_development
    api/index
+   testing
    events 
    other_frameworks
    builds

docs/source/events.rst

@@ -340,7 +340,7 @@ Plugins can listen to this event as cue to register their own global event
 handlers.
 
 roomsAutoJoined
----------------
+~~~~~~~~~~~~~~~
 
 Emitted once any rooms that have been configured to be automatically joined,
 specified via the _`auto_join_rooms` setting, have been entered.

docs/source/index.rst

@@ -1,4 +1,4 @@
-.. Converse.js documentation master file, created by
+.. Converse documentation master file, created by
    sphinx-quickstart on Fri Apr 26 20:48:03 2013.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
@@ -7,14 +7,14 @@
 
     <div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/index.rst">Edit me on GitHub</a></div>
 
-=========================
-Converse.js Documentation
-=========================
+======================
+Converse Documentation
+======================
 
 Preface
 =======
 
-This is the official documentation for Converse.js. If you'd like to
+This is the official documentation for Converse. If you'd like to
 contribute, please read the :doc:`documentation` page.
 
 You might instead be looking for the `User Manual <manual.html>`_.
@@ -22,7 +22,7 @@ You might instead be looking for the `User Manual <manual.html>`_.
 Introduction
 ============
 
-Converse.js is a free and open-source `XMPP <http://xmpp.org/about-xmpp/>`_
+Converse is a free and open-source `XMPP <http://xmpp.org/about-xmpp/>`_
 chat client written in JavaScript which can be tightly integrated into any website.
 
 The benefit of using converse.js as opposed to relying on a SaaS

docs/source/quickstart.rst

@@ -12,7 +12,7 @@ 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/>`_,
+Converse has a `CDN <https://en.wikipedia.org/wiki/Content_delivery_network>`_, provided by `KeyCDN <http://keycdn.com/>`_,
 which hosts its JavaScript and CSS files.
 
 The latest versions of these files are available at these URLs:
@@ -20,7 +20,10 @@ 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
 
-To load a specific version of Converse.js you can put the version in the URL, like so:
+It's however recommended that you load a specific version of Converse, to avoid
+breakage when a new version is released and the above URLs load new resources.
+
+To load a specific version of Converse you can put the version in the URL, like so:
 
 * https://cdn.conversejs.org/4.0.0/dist/converse.min.js
 * https://cdn.conversejs.org/4.0.0/css/converse.min.css
@@ -34,15 +37,15 @@ via the *script* and *link* tags:
     <script src="https://cdn.conversejs.org/dist/converse.min.js" charset="utf-8"></script>
 
 
-.. note:: Instead of always loading the latest version of Converse.js via the
+.. note:: Instead of always loading the latest version of Converse via the
     CDN, it's generally better to load a specific version (preferably the
     latest one), to avoid breakage when new backwards-incompatible versions are
     released.
 
-Initializing Converse.js
-------------------------
+Initializing Converse
+---------------------
 
-You'll then need to initialize Converse.js with configuration settings relevant to your requirements.
+You'll then need to initialize Converse with configuration settings relevant to your requirements.
 Refer to the :ref:`configuration-settings` section for info on all the available configuration settings.
 
 To quickly get started, you can put the following JavaScript code at the
@@ -56,70 +59,27 @@ bottom of your page (after the closing *</body>* element)::
     </script>
 
 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.
-
-Alternative builds of Converse.js
-=================================
-
-The minified ``.js`` and ``.css`` files provide the same functionality as is available
-on the `conversejs.org <https://conversejs.org>`_ website. Useful for testing or demoing.
-
-Converse.js is composed out of plugins, and you are able to exclude certain
-plugins (and to include your own new plugins) when creating a build. This
-enables you to create your own custom builds of Converse.js that differ from
-the standard one.
-
-Besides the standard build, the Converse.js repository includes configuration
-for certain other non-standard builds, which we'll now mention below.
-
-Mobile version
---------------
-
-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 all 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.
-
-Headless build
---------------
-
-There is also the option of making a headless build of converse.js.
-This means a build without any UI but still containing core functionality of
-maintaining a roster, chatboxes and messages.
-
-The file `src/headless.js <https://github.com/jcbrand/converse.js/blob/master/src/headless.js>`_
-is used to determine which plugins are included in the build.
-
-Unfortunately it's currently not yet possible to include Multi-user chat (MUC)
-functionality in the headless build. This is because both the UI and core
-functionality is still contained in one plugin and would first need to be
-split up into two parts, with the UI part dropped for this build.
+Converse repository may serve as a nice usable example.
 
 Fullscreen version
 ------------------
 
-Converse.js also comes in a fullscreen version.
-A hosted version is available online at `inverse.chat <https://inverse.chat>`_.
+Converse also comes in a fullscreen version.
+A hosted version is available online at `conversejs.org/fullscreen <https://conversejs.org/fullscreen.html>`_.
 
 Originally this version was available as a separate build file, but 
 as of version 4.0.0 and higher, the difference between the "overlay" and the
 "fullscreen" versions of converse.js is simply a matter of configuring the 
 :ref:`view_mode`.
 
-To generate the headless build, run ``make dist/converse-headless.js`` and/or 
-``make dist/converse-headless.min.js``.
+For example::
 
+    <script>
+        converse.initialize({
+            bosh_service_url: 'https://conversejs.org/http-bind/', // Please use this connection manager only for testing purposes
+            view_mode: 'fullscreen'
+        });
+    </script>
 
 Where to go from here?
 ======================
@@ -129,10 +89,10 @@ 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
+Perhaps you want to create your own custom build of Converse? Then head over
 to the :doc:`builds` section, or more generally the :doc:`development`
 documentation.
 
-Do you want to know how to theme Converse.js? Then read the :doc:`theming`
+Do you want to know how to theme Converse? Then read the :doc:`theming`
 documentation.
 

docs/source/security.rst

@@ -7,12 +7,12 @@ Security considerations
 =======================
 
 .. note::
-    Converse.js comes with no warranty of any kind and the authors are not liable for any damages.
+    Converse comes with no warranty of any kind and the authors are not liable for any damages.
 
-The data-structures of Converse.js encapsulate sensitive user data such as
+The data-structures of Converse encapsulate sensitive user data such as
 XMPP account details (in case of manual login) and personal conversations.
 
-In an environment where, besides Converse.js, other untrusted 3rd party scripts
+In an environment where, besides Converse, other untrusted 3rd party scripts
 might also be running, it's important to guard against malicious or invasive
 access to user data and/or the API.
 
@@ -22,18 +22,18 @@ The threat model
 The following threat model is considered:
 
 Malicious 3rd party scripts served through compromised side-channels, such as ad-networks,
-which attempt to access Converse.js's API and/or data-structures in order to personify users
+which attempt to access Converse's API and/or data-structures in order to personify users
 or to pilfer their data.
 
 Mitigating measures
 ===================
 
-As of version 3.0.0, the following actions were taken to harden Converse.js against attacks:
+As of version 3.0.0, the following actions were taken to harden Converse against attacks:
 
 Separate code/data into public and private parts
 ------------------------------------------------
 
-1. Encapsulate Converse.js's data structures into a private closured object (named ``_converse``).
+1. Encapsulate Converse's data structures into a private closured object (named ``_converse``).
 2. Split the API into public and private parts.
 
 Restrict access to private code/data
@@ -46,7 +46,7 @@ Restrict access to private code/data
    (otherwise the whitelist could be circumvented).
 
 .. note::
-    Care should be taken when using a custom build of Converse.js where some
+    Care should be taken when using a custom build of Converse where some
     of the core plugins contained in the default build are omitted. In this case
     the omitted plugins should also be removed from the whitelist, otherwise
     malicious plugins could be registered under their names.
@@ -81,12 +81,12 @@ soon as the last tab or window is closed. User credentials are not cached at
 all.
 
 Perhaps the ability to encrypt this cached data could be added in future
-versions of Converse.js, if there is sufficient demand for it.
+versions of Converse, if there is sufficient demand for it.
 
 However to date no significant mitigation or hardening measures have been taken to
 secure this cached data.
 
-Therefore, the best defence as website host is to avoid serving Converse.js with
+Therefore, the best defence as website host is to avoid serving Converse with
 untrusted 3rd party code, and the best defence as an end-user is to avoid chatting
 on websites that host untrusted 3rd party code. The most common examples of such
 being advertising and analytics scripts.

docs/source/setup.rst

@@ -241,20 +241,20 @@ authenticated BOSH session with the XMPP server or a standalone `BOSH <http://xm
 connection manager.
 
 Once authenticated, it receives RID and SID tokens which need to be passed
-on to converse.js upon pa. Converse will then attach to that same session using
+on to Converse. Converse will then attach to that same session using
 those tokens.
 
 It's called "prebind" because you bind to the BOSH session beforehand, and then
 later in the page you just attach to that session again.
 
 The RID and SID tokens can be passed in manually when calling
-`converse.initialize`, but a more convenient way is to pass converse.js a :ref:`prebind_url`
+`converse.initialize`, but a more convenient way is to pass Converse a :ref:`prebind_url`
 which it will call when it needs the tokens. This way it will be able to
 automatically reconnect whenever the connection drops, by simply calling that
 URL again to fetch new tokens.
 
 Prebinding reduces network traffic and also speeds up the startup time for
-converse.js. Additionally, because prebind works with tokens, it's not necessary
+Converse. Additionally, because prebind works with tokens, it's not necessary
 for the XMPP client to know or store users' passwords.
 
 One potential drawback of using prebind is that in order to establish the
@@ -266,11 +266,11 @@ This is however not the case if you for example use LDAP or Active Directory as
 your authentication backend, since you could then configure your XMPP server to
 use that as well.
 
-To prebind you will require a BOSH-enabled XMPP server for converse.js to connect to
+To prebind you will require a BOSH-enabled XMPP server for Converse to connect to
 (see the :ref:`bosh-service-url` under :ref:`configuration-settings`)
 as well as a BOSH client in your web application (written for example in
 Python, Ruby or PHP) that will set up an authenticated BOSH session, which
-converse.js can then attach to.
+Converse can then attach to.
 
 .. note::
     A BOSH server acts as a bridge between HTTP, the protocol of the web, and
@@ -297,7 +297,7 @@ page load). Each page load is a new request which requires a new unique RID.
 The best way to achieve this is to simply increment the RID with each page
 load.
 
-You'll need to configure converse.js with the ``prebind``, :ref:`keepalive` and
+You'll need to configure Converse with the ``prebind``, :ref:`keepalive` and
 :ref:`prebind_url` settings.
 
 Please read the documentation on those settings for a fuller picture of what
@@ -360,4 +360,4 @@ signed with the right key and that they conform to some kind of pre-arranged
 format.
 
 In this case, you would also use the :ref:`credentials_url` setting, to specify a
-URL from which converse.js should fetch the username and token.
+URL from which Converse should fetch the username and token.

docs/source/style_guide.rst

@@ -5,22 +5,13 @@
 Software Style Guide
 ====================
 
-.. note:: Converse.js doesn't yet use any of the new `ES2015
-    <https://babeljs.io/docs/learn-es2015/>`_ features, because we don't
-    rely on a transpiler and still support older browsers.
-
 Most of the style guide recommendations here come from Douglas Crockford's book
 `JavaScript, the good parts <http://shop.oreilly.com/product/9780596517748.do>`_
 
-This style guide is fairly opinionated. Some of these opinions perhaps don't
-conform to your expectations on how JavaScript code should look like.
-I apologize for that. However, for the sake of sanity, consistency and having
-code that is pleasing to the eye, please stick to these guidelines.
-
 Tabs or spaces?
 ---------------
 
-We always indent 4 spaces. Proper indentation is very important for readability.
+We always indent 4 spaces. Proper indentation is important for readability.
 
 Underscores or camelCase?
 -------------------------

docs/source/testing.rst

@@ -0,0 +1,24 @@
+Automated tests
+===============
+
+Converse uses the `Jasmine <https://jasmine.github.io/>`_ testing framework for
+writing tests.
+
+Tests are run in a browser, either manually or automatically via Chrome
+headless.
+
+Adding tests for your bugfix or feature
+----------------------------------------
+
+Take a look at `tests.html <https://github.com/jcbrand/converse.js/blob/master/tests.html>`_
+and the `spec files <https://github.com/jcbrand/converse.js/blob/master/tests.html>`_
+to see how tests are implemented.
+
+Running tests
+-------------
+
+Check that all tests complete sucessfully.
+
+Run ``make check`` in your terminal.
+
+To run the tests manually, run ``make serve`` and then open `http://localhost:8000/tests <https://github.com/jcbrand/converse.js/blob/master/tests.html>`_ in your browser.

docs/source/theming.rst

@@ -11,7 +11,7 @@ Theming
 Setting up your environment
 ===========================
 
-In order to theme converse.js, you first need to set up a :ref:`development` environment.
+In order to theme Converse, you first need to set up a :ref:`development` environment.
 
 You'll also want to preview the changes you make in your browser, for which a
 webserver will be useful.
@@ -28,7 +28,7 @@ serve the files for you, simply run::
     Windows you can use `Chocolatey <https://chocolatey.org/>`_.
 
 After running ``make serve`` you can open http://localhost:8000 in your webbrowser you'll
-see the converse.js website.
+see the Converse website.
 
 However, when developing or changing the theme, you'll want to load all the
 unminified JS and CSS resources as separate files. To do this, open http://localhost:8000/dev.html
@@ -37,7 +37,7 @@ instead.
 Mockups
 =======
 
-Converse.js contains some mockups in the ``./mockup`` directory against which you
+Converse contains some mockups in the ``./mockup`` directory against which you
 can preview and tweak your changes.
 
 The ``./mockup/index.html`` file contains the most comprehensive mockup, while
@@ -46,13 +46,13 @@ the other files focus on particular UI aspects.
 To see it in your browser, simply open: http://localhost:8000/mockup
 
 
-Modifying the HTML templates of Converse.js
-===========================================
+Modifying the HTML templates of Converse
+========================================
 
-The HTML markup of converse.js is contained in small ``.html`` files in the
+The HTML markup of Converse is contained in small ``.html`` files in the
 ``./src/templates`` directory.
 
-You can modify HTML markup that converse.js generates by modifying these files.
+You can modify HTML markup that Converse generates by modifying these files.
 
 Modifying the CSS
 =================
@@ -66,7 +66,7 @@ To generate the CSS you can run::
 Creating dist files
 ===================
 
-Once you've themed converse.js, you'll want to create new minified distribution
+Once you've themed Converse, you'll want to create new minified distribution
 files of all the JavaScript and CSS.
 
 Please refer to the :doc:`builds` section for information on how this is done.

docs/source/translations.rst

@@ -6,17 +6,17 @@
 Translations
 ============
 
-Converse.js supports localization of its user interface and date formats. As
+Converse supports localization of its user interface and date formats. As
 of writing, 17 languages are supported.
 
-The translations of converse.js can be found in the `locale
+The translations of Converse can be found in the `locale
 <https://github.com/jcbrand/converse.js/tree/master/locale>`_ directory.
 
-Translations of Converse.js are very welcome. You can add translations either
+Translations of Converse are very welcome. You can add translations either
 manually by editing the ``.po`` files in the above-mentioned ``locale``
 directory, or through the web at `weblate <https://hosted.weblate.org/projects/conversejs/#languages>`_.
 
-As of version 3.3.0, converse.js no longer automatically bundles translations
+As of version 3.3.0, Converse no longer automatically bundles translations
 in its source file and instead fetches only the relevant locale for the current
 session from a URL as specified by the :ref:`locales-url` setting.
 
@@ -34,7 +34,7 @@ If you simply want to add a few missing translations, then consider doing it
 through the web at `weblate <https://hosted.weblate.org/projects/conversejs/#languages>`_.
 
 Some things however cannot be done via weblate and instead have to be done
-manually in a checkout of the converse.js source repository.
+manually in a checkout of the Converse source repository.
 
 These tasks are documented below.
 
@@ -46,7 +46,7 @@ The gettext `.pot` file located in
 is the template containing all translations and from which for each language an individual PO
 file is generated.
 
-The `.pot` file contains all translateable strings extracted from converse.js.
+The `.pot` file contains all translateable strings extracted from Converse.
 
 To make a user-facing string translateable, wrap it in the double underscore helper
 function like so:
@@ -64,7 +64,7 @@ After adding the string, you'll need to regenerate the POT file:
 Making translations file for a new language
 -------------------------------------------
 
-To create a new translations file for a language in which converse.js is not yet
+To create a new translations file for a language in which Converse is not yet
 translated into, do the following
 
 .. note:: In this example we use Polish (pl), you need to substitute 'pl' to your own language's code.
@@ -108,7 +108,7 @@ Generating a JSON file from a translations file
 -----------------------------------------------
 
 Unfortunately `Jed <http://slexaxton.github.io/Jed>`_, which we use for
-translations in converse.js cannot use the `.po` files directly. We have
+translations in Converse cannot use the `.po` files directly. We have
 to generate from it a file in JSON format and then put that in a `.js` file
 for the specific language.
 

docs/source/troubleshooting.rst

@@ -6,16 +6,16 @@
 Troubleshooting and debugging
 =============================
 
-General tips on debugging Converse.js
-=====================================
+General tips on debugging Converse
+==================================
 
-When debugging converse.js, always make sure that you pass in ``debug: true`` to
+When debugging Converse, always make sure that you pass in ``debug: true`` to
 the ``converse.initialize`` call.
 
-Converse.js will then log debug information to the browser's developer console.
+Converse will then log debug information to the browser's developer console.
 Open the developer console and study the data that is logged to it.
 
-`Strope.js <http://strophe.im/>`_ the underlying XMPP library which Converse.js
+`Strope.js <http://strophe.im/>`_ the underlying XMPP library which Converse
 uses, swallows errors, so that messaging can continue in cases where
 non-critical errors occur.
 
@@ -26,88 +26,21 @@ That's why checking the debug output in the browser console is so important. If
 something goes wrong somewhere, the error will be logged there and you'll be
 able to see it.
 
-Additionally, Converse.js will in debug mode also log all XMPP stanzas
+Additionally, Converse will in debug mode also log all XMPP stanzas
 (the XML snippets being sent between it and the server) to the console.
 This is very useful for debugging issues relating to the XMPP protocol.
 
 For example, if a message or presence update doesn't appear, one of the first
 things you can do is to set ``debug: true`` and then to check in the console
 whether the relevant XMPP stanzas are actually logged (which would mean that
-they were received by Converse.js). If they're not logged, then the problem is
+they were received by Converse). If they're not logged, then the problem is
 more likely on the XMPP server's end (perhaps a misconfiguration?). If they
-**are** logged, then there might be a bug or misconfiguration in Converse.js.
-
-
-Conflicts with other JavaScript libraries
-=========================================
-
-Problem: 
----------
-
-You are using other JavaScript libraries (like JQuery plugins), and
-get errors like these in your browser console::
-
-    Uncaught TypeError: Object [object Object] has no method 'xxx' from example.js
-
-Solution:
----------
-
-First, find out which object is referred to by ``Object [object Object]``.
-
-It will probably be the jQuery object ``$`` or perhaps the lodash/underscore object ``_``.
-
-For the purpose of demonstration, I'm going to assume its ``$``, but the same
-rules apply if its something else.
-
-The bundled and minified default build of converse.js, ``converse.min.js``
-includes within it all of converse.js's dependencies, which include for example *jQuery*.
-
-If you are having conflicts where attributes or methods aren't available 
-on the jQuery object, you are probably loading ``converse.min.js`` (which
-includes jQuery) as well as your own jQuery version separately.
-
-What then happens is that there are two ``$`` objects (one from
-converse.js and one from the jQuery version you included manually)
-and only one of them has been extended to have the methods or attributes you require.
-
-Which jQuery object you get depends on the order in which you load the libraries.
-
-There are multiple ways to solve this issue.
-
-Firstly, make sure whether you really need to include a separate version of
-jQuery. Chances are that you don't. If you can remove the separate
-version, your problem should be solved, as long as your libraries are loaded in
-the right order.
-
-Either case, whether you need to keep two versions or not, the solution depends
-on whether you'll use require.js to manage your libraries or whether you'll
-load them manually.
-
-With require.js
-~~~~~~~~~~~~~~~
-
-Instead of using ``converse.min.js``, manage all the libraries in your project
-(i.e. converse.js and its dependencies plus all other libraries you use) as one
-require.js project, making sure everything is loaded in the correct order.
-
-Then, before deployment, you make your own custom minified build that bundles everything
-you need.
-
-With <script> tags
-~~~~~~~~~~~~~~~~~~
-
-Take a look at `non_amd.html <https://github.com/jcbrand/converse.js/blob/master/non_amd.html>`_
-in the converse.js repo.
-
-It shows in which order the libraries must be loaded via ``<script>`` tags. Add
-your own libraries, making sure that they are loaded in the correct order (e.g.
-jQuery plugins must load after jQuery).
-
+**are** logged, then there might be a bug or misconfiguration in Converse.
 
 Performance issues with large rosters
 =====================================
 
-Effort has been made to benchmark and optimize converse.js to work with large
+Effort has been made to benchmark and optimize Converse to work with large
 rosters.
 
 See for example the benchmarking tests in `spec/profiling.js
@@ -117,7 +50,7 @@ Chrome <https://developer.chrome.com/devtools/docs/cpu-profiling>`_ to find
 bottlenecks in the code.
 
 However, with large rosters (more than 1000 contacts), rendering in
-converse.js slows down a lot and it may become intolerably slow.
+Converse slows down a lot and it may become intolerably slow.
 
 One simple trick to improve performance is to set ``show_only_online_users: true``.
 This will (usually) reduce the amount of contacts that get rendered in the