Split the documentation out into subfiles.

docs/source/builds.rst

+======================
+Creating custom builds
+======================
+
+.. contents:: Table of Contents
+   :depth: 3
+   :local:
+
+
+.. warning:: There current documentation in this section does not adequately
+    explain how to create custom builds.
+
+.. _`minification`:
+
+Minification
+============
+
+Minifying Javascript and CSS
+----------------------------
+
+Please make sure to read the section :doc:`development` and that you have installed
+all development dependencies (long story short, you can run ``npm install``
+and then ``grunt fetch``).
+
+We  use `require.js <http://requirejs.org>`_ to keep track of *Converse.js* and its dependencies and to
+to bundle them together in a single minified file fit for deployment to a
+production site.
+
+To minify the Javascript and CSS, run the following command:
+
+::
+
+    grunt minify
+
+Javascript will be bundled and minified with `require.js`_'s optimization tool,
+using `almond <https://github.com/jrburke/almond>`_.
+
+You can `read more about require.js's optimizer here <http://requirejs.org/docs/optimization.html>`_.
+
+CSS is minified via `cssmin <https://github.com/gruntjs/grunt-contrib-cssmin>`_.

docs/source/features.rst

+========
+Features
+========
+
+.. contents:: Table of Contents
+   :depth: 2
+   :local:
+
+Off-the-record encryption
+=========================
+
+Converse.js supports `Off-the-record (OTR) <https://otr.cypherpunks.ca/>`_
+encrypted messaging.
+
+The OTR protocol not only **encrypts your messages**, it provides ways to
+**verify the identity** of the person you are talking to,
+**plausible deniability** and **perfect forward secrecy** by generating
+new encryption keys for each conversation.
+
+In its current state, Javascript cryptography is fraught with dangers and
+challenges that make it impossible to reach the same standard of security that
+is available with native "desktop" software.
+
+This is due to its runtime malleability, the way it is "installed" (e.g.
+served) and the browser's lack of cryptographic primitives needed to implement
+secure crypto.
+
+For harsh but fairly valid criticism of Javascript cryptography, read:
+`Javascript Cryptography Considered Harmful <http://www.matasano.com/articles/javascript-cryptography/>`_.
+
+To get an idea on how this applies to OTR support in Converse.js, please read
+`my thoughts on it <https://opkode.com/media/blog/2013/11/11/conversejs-otr-support>`_.
+
+For now, suffice to say that although its useful to have OTR support in
+Converse.js in order to avoid most eavesdroppers, if you need serious
+communications privacy, then you're much better off using native software.
+
+Sound Notifications
+===================
+
+From version 0.8.1 Converse.js can play a sound notification when you receive a
+message.
+
+For more info, please see the :ref:`play-sounds` configuration setting.
+
+Multilingual Support
+====================
+
+Converse.js is translated into multiple languages. The default build,
+``converse.min.js``, includes all languages.
+
+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
+==========
+
+Commands
+--------
+
+Here are the different commands that may be used in a chat room:
+
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
+| Event Type | When is it triggered?                                                                        | Example (substitue $nickname with an actual user's nickname)  |
++============+==============================================================================================+===============================================================+
+| **ban**    | Ban a user from the chat room. They will not be able to join again.                          | /ban $nickname                                                |
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
+| **clear**  | Clear the messages shown in the chat room.                                                   | /clear                                                        |
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
+| **deop**   | Make a moderator a normal participant.                                                       | /deop $nickname [$reason]                                     |
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
+| **help**   | Show the list of available commands.                                                         | /help                                                         |
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
+| **kick**   | Kick a user out of a room. They will be able to join again.                                  | /kick $nickname [$reason]                                     |
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
+| **me**     | Speak in the 3rd person.                                                                     | /me $message                                                  |
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
+| **mute**   | Remove a user's ability to post messages to the room. They will still be able to observe.    | /mute $nickname [$reason]                                     |
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
+| **nick**   | Change your nickname.                                                                        | /nick $nickname                                               |
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
+| **op**     | Make a normal participant a moderator.                                                       | /op $nickname [$reason]                                       |
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
+| **topic**  | Set the topic of the chat room.                                                              | /topic ${topic text}                                          |
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
+| **voice**  | Allow a muted user to post messages to the room.                                             | /voice $nickname [$reason]                                    |
++------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+

docs/source/quickstart.rst

+=========================================
+Quickstart (to get a demo up and running)
+=========================================
+
+When you download a specific release of *Converse.js* there will be two minified files inside the zip file.
+
+* builds/converse.min.js
+* css/converse.min.css
+
+You can include these two files inside the *<head>* element of your website via the *script* and *link*
+tags:
+
+.. code-block:: html
+
+    <link rel="stylesheet" type="text/css" media="screen" href="css/converse.min.css">
+    <script src="builds/converse.min.js"></script>
+
+You need to initialize Converse.js with configuration settings according to
+your requirements.
+
+Please refer to the :ref:`configuration-variables` section further below for info on
+all the available configuration settings.
+
+To configure Converse.js, put the following inline Javascript code at the
+bottom of your page (after the closing *</body>* element).
+
+.. code-block:: javascript
+
+    require(['converse'], function (converse) {
+        converse.initialize({
+            auto_list_rooms: false,
+            auto_subscribe: false,
+            bosh_service_url: 'https://bind.conversejs.org', // Please use this connection manager only for testing purposes
+            hide_muc_server: false,
+            i18n: locales.en, // Refer to ./locale/locales.js to see which locales are supported
+            prebind: false,
+            show_controlbox_by_default: true,
+            roster_groups: true
+        });
+    });
+
+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 files provide the same demo-like 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 single persistent 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.
+
+For more info on this, read: :ref:`session-support`.
+
+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/setup.rst

+=====================
+Setup and integration
+=====================
+
+.. contents:: Table of Contents
+   :depth: 2
+   :local:
+
+.. _what-you-will-need:
+
+------------------
+What you will need
+------------------
+
+An XMPP server
+==============
+
+*Converse.js* implements `XMPP <http://xmpp.org/about-xmpp/>`_ as its
+messaging protocol, and therefore needs to connect to an XMPP/Jabber
+server (Jabber is really just a synonym for XMPP).
+
+You can connect to public XMPP servers like ``jabber.org`` but if you want to
+have :ref:`session support <session-support>` you'll have to set up your own XMPP server.
+
+You can find a list of public XMPP servers/providers on `xmpp.net <http://xmpp.net>`_ and a list of
+servers that you can set up yourself on `xmpp.org <http://xmpp.org/xmpp-software/servers/>`_.
+
+
+A BOSH Connection Manager
+=========================
+
+Your website and *Converse.js* use `HTTP <https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol>`_
+as protocol to communicate with the webserver. HTTP connections are stateless and usually shortlived.
+
+`XMPP <https://en.wikipedia.org/wiki/Xmpp>`_ on the other hand, is the protocol that enables instant messaging, and
+its connections are stateful and usually longer.
+
+To enable a web application like *Converse.js* to communicate with an XMPP
+server, we need a proxy in the middle that can act as a bridge between the two
+protocols.
+
+The `index.html <https://github.com/jcbrand/converse.js/blob/master/index.html>`_ file inside the
+
+This is the job of a connection manager. A connection manager can be either a
+standalone application or part of an XMPP server. Popular XMPP servers such as
+`ejabberd <http://www.ejabberd.im>`_, `prosody <http://prosody.im/doc/setting_up_bosh>`_ and
+`openfire <http://www.igniterealtime.org/projects/openfire/>`_ all include their own connection managers
+(but you usually have to enable them in the configuration).
+
+Standalone connection managers also exist, see for example `Punjab <https://github.com/twonds/punjab>`_.
+
+The demo on the `Converse.js homepage <http://conversejs.org>`_ uses a connection manager located at https://bind.conversejs.org.
+This connection manager is available for testing purposes only, please don't use it in production.
+
+Overcoming cross-domain request restrictions
+--------------------------------------------
+
+Lets say your domain is *example.org*, but the domain of your connection
+manager is *example.com*.
+
+HTTP requests are made by *Converse.js* to the connection manager via XmlHttpRequests (XHR).
+Until recently, it was not possible to make such requests to a different domain
+than the one currently being served (to prevent XSS attacks).
+
+Luckily there is now a standard called 
+`CORS <https://en.wikipedia.org/wiki/Cross-origin_resource_sharing>`_ 
+(Cross-origin resource sharing), which enables exactly that.
+Modern browsers support CORS, but there are problems with Internet Explorer < 10.
+
+IE 8 and 9 partially support CORS via a proprietary implementation called
+XDomainRequest. There is a `Strophe.js plugin <https://gist.github.com/1095825/6b4517276f26b66b01fa97b0a78c01275fdc6ff2>`_
+which you can use to enable support for XDomainRequest when it is present.
+
+In IE < 8, there is no support for CORS.
+
+Instead of using CORS, you can add a reverse proxy in
+Apache/Nginx which serves the connection manager under the same domain as your
+website. This will remove the need for any cross-domain XHR support.
+
+For example:
+~~~~~~~~~~~~
+
+Assuming your site is accessible on port ``80`` for the domain ``mysite.com``
+and your connection manager manager is running at ``someothersite.com/http-bind``.
+
+The *bosh_service_url* value you want to give Converse.js to overcome
+the cross-domain restriction is ``mysite.com/http-bind`` and not
+``someothersite.com/http-bind``.
+
+Your ``nginx`` or ``apache`` configuration will look as follows:
+
+Nginx
+~~~~~
+
+.. code-block:: nginx 
+
+    http {
+        server {
+            listen       80
+            server_name  mysite.com;
+            location ~ ^/http-bind/ {
+                proxy_pass http://someothersite.com;
+            }
+        }
+    }
+
+Apache
+~~~~~~
+
+.. code-block:: apache
+
+    <VirtualHost *:80>
+        ServerName mysite.com
+        RewriteEngine On
+        RewriteRule ^/http-bind(.*) http://someothersite.com/http-bind$1 [P,L]
+    </VirtualHost>
+
+
+Server-side authentication
+==========================
+
+.. _`session-support`:
+
+Prebinding and Single Session Support
+-------------------------------------
+
+It's possible to enable single-site login, whereby users already
+authenticated in your website will also automatically be logged in on the chat server,
+
+This session should also persist across page loads. In other words, we don't
+want the user to have to give their chat credentials every time they reload the
+page.
+
+To do this you will require a `BOSH server <http://xmpp.org/about-xmpp/technology-overview/bosh/>`_
+for converse.js to connect to (see the :ref:`bosh-service-url` under :ref:`configuration-variables`)
+as well as a BOSH client on your own server (written for example in Python, Ruby or PHP) that will
+do the pre-authentication before the web page loads.
+
+.. note::
+    A BOSH server acts as a bridge between HTTP, the protocol of the web, and
+    XMPP, the instant messaging protocol.
+    Converse.js can only communicate via HTTP, but we need to communicate with
+    an XMPP server in order to chat. So the BOSH server acts as a middle man,
+    translating our HTTP requests into XMPP stanzas and vice versa.
+
+Jack Moffitt has a great `blogpost <http://metajack.im/2008/10/03/getting-attached-to-strophe>`_
+about this and even provides an
+`example Django application <https://github.com/metajack/strophejs/tree/master/examples/attach>`_
+to demonstrate it.
+
+When you authenticate to the XMPP server on your backend application (for
+example via a BOSH client in Django), you'll receive two tokens, RID (request ID) and SID (session ID).
+
+The **Session ID (SID)** is a unique identifier for the current *session*. This
+number stays constant for the entire session.
+
+The **Request ID (RID)** is a unique identifier for the current *request* (i.e.
+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.
+
+When you initialize converse.js in your browser, you need to pass it these two
+tokens. Converse.js will then use them to attach to the session you just
+created.
+
+You can embed the RID and SID tokens in your HTML markup or you can do an
+XMLHttpRequest call to your server and ask it to return them for you.
+
+Below is one example of how this could work. An Ajax call is made to the
+relative URL **/prebind** and it expects to receive JSON data back.
+
+.. code-block:: javascript
+
+    $.getJSON('/prebind', function (data) {
+        converse.initialize({
+            prebind: true,
+            bosh_service_url: data.bosh_service_url,
+            jid: data.jid,
+            sid: data.sid,
+            rid: data.rid
+        });
+    );
+
+**Here's what's happening:**
+
+The JSON data returned from the Ajax call to example.com/prebind contains the user's JID (jabber ID), RID, SID and the URL to the
+BOSH server (also called a *connection manager*).
+
+These values are then passed to converse.js's ``initialize`` method.
+
+.. note::
+   If you want to enable single session support, you need to set **prebind: true**
+   when calling **converse.initialize** (see ./index.html).
+   Additionally you need to pass in valid **jid**, **sid**, **rid** and
+   **bosh_service_url** values.
+
+
+Example code for server-side prebinding
+---------------------------------------
+
+* PHP:
+    See `xmpp-prebind-php <https://github.com/candy-chat/xmpp-prebind-php>`_ by
+    Michael Weibel and the folks from Candy chat.
+
+* Python:
+    See this `example Django application`_ by Jack Moffitt.

docs/source/translations.rst

+============
+Translations
+============
+
+.. contents:: Table of Contents
+   :depth: 2
+   :local:
+
+.. note::
+   Translations take up a lot of space and will bloat your minified file.
+   At the time of writing, all the translations add about 50KB of extra data to
+   the minified javascript file. Therefore, make sure to only
+   include those languages that you intend to support and remove from
+   ./locale/locales.js those which you don't need. Remember to rebuild the
+   minified file afterwards.
+
+The gettext POT file located in ./locale/converse.pot 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.
+
+To make a user facing string translateable, wrap it in the double underscore helper
+function like so:
+
+.. code-block:: javascript
+
+    __('This string will be translated at runtime');
+
+After adding the string, you'll need to regenerate the POT file, like so:
+
+::
+
+    make pot
+
+To create a new PO file for a language in which converse.js 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.
+
+::
+
+    mkdir -p ./locale/pl/LC_MESSAGES
+    msginit -i ./locale/converse.pot -o ./locale/pl/LC_MESSAGES/converse.po -l pl
+
+You can then create or update the PO file for a specific language by doing the following:
+
+.. note:: In this example we use German (de), you need to substitute 'de' to your own language's code.
+
+::
+
+    msgmerge ./locale/de/LC_MESSAGES/converse.po ./locale/converse.pot -U
+
+To do this for ALL languages, run:
+
+::
+
+    make po
+
+The resulting PO file is then what gets translated.
+
+If you've created a new PO file, please make sure to add the following
+attributes at the top of the file (under *Content-Transfer-Encoding*). They are
+required as configuration settings for Jed, the Javascript translations library
+that we're using.
+
+.. code-block:: po
+
+    "domain: converse\n"
+    "lang: de\n"
+    "plural_forms: nplurals=2; plural=(n != 1);\n"
+
+
+Unfortunately `Jed <http://slexaxton.github.io/Jed>`_ 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.
+
+To generate JSON from a PO file, you'll need po2json for node.js. Run the
+following command to install it (npm being the node.js package manager):
+
+::
+
+    npm install po2json
+
+You can then convert the translations into JSON format:
+
+::
+
+    po2json locale/de/LC_MESSAGES/converse.po locale/de/LC_MESSAGES/converse.json
+
+Now from converse.json paste the data as a value for the "locale_data" key in the
+object in the language's .js file.
+
+So, if you are for example translating into German (language code 'de'), you'll
+create or update the file ./locale/LC_MESSAGES/de.js with the following code:
+
+.. code-block:: javascript 
+
+    (function (root, factory) {
+        define("de", ['jed'], function () {
+            return factory(new Jed({
+                "domain": "converse",
+                "locale_data": {
+                    // Paste the JSON data from converse.json here
+                }
+            })
+        }
+    }(this, function (i18n) {
+        return i18n;
+    }));
+
+making sure to also paste the JSON data as value to the "locale_data" key.
+
+.. note::
+    If you are adding translations for a new language that is not already supported,
+    you'll have to add the language path in main.js and make one more edit in ./locale/locales.js
+    to make sure the language is loaded by require.js.
+
+Congratulations, you've now succesfully added your translations. Sorry for all
+those hoops you had to jump through.