Add more documentation around file sharing and CORS

docs/source/features.rst

@@ -2,22 +2,32 @@
 
     <div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/features.rst">Edit me on GitHub</a></div>
 
+.. _`features`:
+
 ========
 Features
 ========
 
-Open chats via URL
-==================
+File sharing (`XEP-0363 HTTP File Upload <https://xmpp.org/extensions/xep-0363.html>`_)
+=======================================================================================
 
-From version 3.3.0, converse.js now has the ability to open chats (private or
-groupchat) based on the URL fragment.
+Converse supports file sharing by first uploading the file to a file server and
+then sending the file's URL to the recipient.
 
-A room (aka groupchat) can be opened with a URL fragment such as `#converse/room?jid=room@domain`
-and a private chat with a URL fragment such as
-`#converse/chat?jid=user@domain`.
+The file server that is used is configured by the XMPP server admin, and is not
+something that Converse has any control over.
+
+Often when people report file sharing not working, it's because the file server
+is not configured to allow file uploads from other domains.
 
-XEP-0384 OMEMO Encryption
-=========================
+The file server needs to be configured for `Cross-Origin resource sharing <https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS>`_
+(known by the acronym CORS). Specifically, it needs to add a
+``Access-Control-Allow-Origin`` header which includes the domain hosting
+Converse.
+
+
+End to end message encryption (`XEP-0384 OMEMO <https://xmpp.org/extensions/xep-0363.html>`_)
+=============================================================================================
 
 Converse supports OMEMO encryption based on the
 `Signal Protocol <https://github.com/signalapp/libsignal-protocol-javascript>`_.
@@ -83,6 +93,18 @@ articles:
 * `What's wrong with webcrypto? <https://tonyarcieri.com/whats-wrong-with-webcrypto>`_
 * `Heartbleed and JavaScript crypto <https://tankredhase.com/2014/04/13/heartbleed-and-javascript-crypto/>`_
 
+
+Open chats via URL
+==================
+
+From version 3.3.0, converse.js now has the ability to open chats (private or
+groupchat) based on the URL fragment.
+
+A room (aka groupchat) can be opened with a URL fragment such as `#converse/room?jid=room@domain`
+and a private chat with a URL fragment such as
+`#converse/chat?jid=user@domain`.
+
+
 Notifications
 =============
 

docs/source/quickstart.rst

@@ -20,10 +20,11 @@ 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
 
-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.
+If you are integrating Converse into an existing website or app, then we recommend
+that you load a specific version of Converse. Otherwise your website or app
+might break when a new backwards-incompatible version of Converse is released.
 
-To load a specific version of Converse you can put the version in the URL, like so:
+To load a specific version of Converse you can put the version in the URL:
 
 * https://cdn.conversejs.org/4.0.4/dist/converse.min.js
 * https://cdn.conversejs.org/4.0.4/css/converse.min.css
@@ -33,28 +34,19 @@ via the *script* and *link* tags:
 
 .. code-block:: html
 
-    <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" charset="utf-8"></script>
-
-
-.. 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.
+    <link rel="stylesheet" type="text/css" media="screen" href="https://cdn.conversejs.org/4.0.4/css/converse.min.css">
+    <script src="https://cdn.conversejs.org/4.0.4/dist/converse.min.js" charset="utf-8"></script>
 
 
 Option 2: Building the files yourself
 -------------------------------------
 
-Instead of using the CDN, you can also create your own builds and host them
-yourself.
+Instead of using the CDN, you can also create your own builds and host them yourself.
 
-Have a look at the :ref:`creating_builds` section on how to create your own
-builds.
+Have a look at the :ref:`creating_builds` section on how to create your own builds.
 
-Long story short, you should be able to do it by running `make dist`, but you
-might need to install some development libraries on your system first
-(e.g. gcc, libffi-dev and ruby-dev).
+In short, you should be able to do it by running ``make dist`` inside a
+checkout of the `Converse repo <http://github.com/conversejs/converse.js/>`_.
 
 Besides including the ``converse.min.js`` and ``converse.min.css`` files,
 you'll also need to make sure that the ``webfonts`` directory is available in
@@ -64,8 +56,8 @@ the same location as ``converse.min.css``.
 Initializing Converse
 ---------------------
 
-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.
+You'll need to initialize Converse with configuration settings relevant to your requirements.
+Take a look at the :ref:`configuration-settings` section for info on all the available settings.
 
 To quickly get started, you can put the following JavaScript code at the
 bottom of your page (after the closing *</body>* element)::
@@ -78,7 +70,7 @@ 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 repository may serve as a nice usable example.
+Converse repository serves as a nice, usable example.
 
 Fullscreen version
 ------------------
@@ -103,15 +95,19 @@ For example::
 Where to go from here?
 ======================
 
+Have a look at the various :ref:`features <features>` that Converse provides, for some of
+them you might have to do more setup work, like configuring an XMPP server or
+webserver.
+
 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? Then head over
-to the :doc:`builds` section, or more generally the :doc:`development`
+to the :doc:`builds` section, or more generally the :doc:`development <development>`
 documentation.
 
-Do you want to know how to theme Converse? Then read the :doc:`theming`
+Do you want to know how to theme Converse? Then read the :doc:`theming <theming>`
 documentation.
 

docs/source/setup.rst

@@ -129,30 +129,35 @@ configure Converse to connect to a websocket URL.
 The Webserver
 =============
 
-.. _CORS:
-
-Overcoming cross-domain request restrictions
---------------------------------------------
-
 Lets say the domain under which you host Converse is *example.org:80*,
 but the domain of your connection manager or the domain of
 your HTTP file server (for `XEP-0363 HTTP File Upload <https://xmpp.org/extensions/xep-0363.html>`_)
 is at a different domain, either a different port like *example.org:5280* or a
 different name like *elsehwere.org*.
 
-In cases like this, cross-domain request restrictions of the browser come into
-force. For security purposes a browser does not by default allow a website to
+In such a situation the same-origin security policy of the browser comes into force.
+For security purposes a browser does not by default allow a website to
 make certain types of requests to other domains.
 
-One solution is to add a reverse proxy to a webserver such as Nginx or Apache to ensure that
-all services you use are hosted under the same domain name and port.
+There are two ways in which you can solve this problem.
+
+.. _CORS:
+
+1. Cross-Origin Resource Sharing (CORS)
+---------------------------------------
+
+CORS is a technique for overcoming browser restrictions related to the
+`same-origin security policy <https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy>`_.
 
-Alternatively you can use something called `CORS <https://en.wikipedia.org/wiki/Cross-origin_resource_sharing>`__
-(Cross-origin resource sharing).
+CORS is enabled by adding an ``Access-Control-Allow-Origin`` header. Where this
+is configured depends on what webserver is used for your file upload server.
 
-By enabling CORS on the non-local domains (e.g. *elsewhere.org*, when
-*example.org* is the local domain), you allow the browser to make requests to it.
 
+2. Reverse-proxy 
+----------------
+
+Another possible solution is to add a reverse proxy to a webserver such as Nginx or Apache to ensure that
+all services you use are hosted under the same domain name and port.
 
 Examples:
 *********

docs/source/troubleshooting.rst

@@ -56,13 +56,30 @@ 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
 roster, which eases one of the remaining performance bottlenecks.
 
-404 response for an OPTIONS request
-===================================
+File upload is not working
+==========================
 
-This often happens when trying to upload a file to the XEP-0363 file server
-which is under a different domain or port than the one that's hosting Converse.
+One of the most common causes for file upload not working is a lack of CORS
+support by the file server to which the file should be uploaded.
 
-An OPTIONS request usually a so-called
+CORS stands for `Cross-Origin Resource Sharing (CORS) <https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS>`_
+and is a technique for overcoming browser restrictions related to the
+`same-origin security policy <https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy>`_.
+
+For example, if the domain under which you host Converse is *example.org*,
+but the domain of your of your HTTP file server (for `XEP-0363 HTTP File Upload <https://xmpp.org/extensions/xep-0363.html>`_)
+is *upload.example.org*, then the HTTP file server needs to enable CORS.
+
+If you're not sure what the domain of the HTTP file server is, take a look at
+the console of your browser's developer tools.
+
+You might see an error like this one::
+
+    Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at https://example.de:5443/...
+
+You might also see a 404 HTTP response for an OPTIONS request in the `Network Tab` of your browser's developer tools.
+
+An OPTIONS request is usually a so-called
 `CORS pre-flight request <https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS#Preflighted_requests_in_CORS>`_
 which is used by the browser to find out whether the endpoint supports
 `Cross-Origin Resource Sharing (CORS) <https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS>`_.
@@ -70,6 +87,11 @@ which is used by the browser to find out whether the endpoint supports
 If you get a 404 response for such a request, then the endpoint does NOT
 support CORS and the browser will prevent requests from being made to it.
 
-This will prevent you from uploading images to it.
+This will prevent you from uploading files to it.
+
+How you solve a CORS-related issue depends on your particular setup, specifically it depends on
+what you're using as the HTTP file server.
+
+CORS is enabled by adding an ``Access-Control-Allow-Origin`` header, so you'll
+have to configure your file server to add this header.
 
-Take a look at the section ":ref:`CORS`" for more information on how to solve this problem.