Docs: Clarify offline compression. Fixes django-compressor#680.

docs/behind-the-scenes.txt

@@ -1,32 +1,32 @@
 .. _behind_the_scenes:
 
-Behind the scenes
+Behind the Scenes
 =================
 
 This document assumes you already have an up and running instance of
 Django Compressor, and that you understand how to use it in your templates.
 The goal is to explain what the main template tag, {% compress %}, does
 behind the scenes, to help you debug performance problems for instance.
 
-Offline cache
+Offline compression
 -------------
 
-If offline cache is activated, the first thing {% compress %} tries to do is
+If offline compression is activated, the {% compress %} tag will try to
 retrieve the compressed version for its nodelist from the offline manifest
 cache. It doesn't parse, doesn't check the modified times of the files, doesn't
 even know which files are concerned actually, since it doesn't look inside the
 nodelist of the template block enclosed by the ``compress`` template tag.
 The offline cache manifest is just a json file, stored on disk inside the
 directory that holds the compressed files. The format of the manifest is simply
-a key <=> value dictionary, with the hash of the nodelist being the key,
+a key-value dictionary, with the hash of the nodelist being the key,
 and the HTML containing the element code for the combined file or piece of code
-being the value. Generating the offline manifest, using the ``compress``
-management command, also generates the combined files referenced in the manifest.
+being the value. The ``compress`` management command generates the
+offline manifest as well as the combined files referenced in the manifest.
 
-If offline cache is activated and the nodelist hash can not be found inside the
+If offline compression is enabled and the nodelist hash can not be found inside the
 manifest, {% compress %} will raise an ``OfflineGenerationError``.
 
-If offline cache is de-activated, the following happens:
+If offline compression is disabled, the following happens:
 
 First step: parsing and file list
 ---------------------------------

docs/remote-storages.txt

@@ -1,6 +1,6 @@
 .. _remote_storages:
 
-Remote storages
+Remote Storages
 ---------------
 
 In some cases it's useful to use a CDN_ for serving static files such as

docs/scenarios.txt

@@ -45,7 +45,9 @@ You will find offline compression beneficial if:
   :attr:`~django.conf.settings.COMPRESS_PRECOMPILERS` binaries in one
   location.
 
-* You store compressed files on a CDN. 
+* You store compressed files on a CDN.
+
+* You want the best possible performance.
 
 Caveats
 -------

docs/settings.txt

@@ -459,9 +459,7 @@ Offline settings
     :Default: ``False``
 
     Boolean that decides if compression should be done outside of the
-    request/response loop. (See :ref:`behind_the_Scenes` for more.) This allows
-    to pre-compress CSS and JavaScript files and works just like the automatic
-    compression with the ``{% compress %}`` tag.
+    request/response loop. See :ref:`offline_compression` for details.
 
 .. attribute:: COMPRESS_OFFLINE_TIMEOUT
 

docs/usage.txt

@@ -107,22 +107,22 @@ access it in the `post_compress signal <signals>`.
 .. _memcached: http://memcached.org/
 .. _caching documentation: https://docs.djangoproject.com/en/1.8/topics/cache/#memcached
 
-.. _pre-compression:
 
-Pre-compression
+.. _offline_compression:
+
+Offline Compression
 ---------------
 
-Django Compressor comes with an optional ``compress`` management command to
-run the compression outside of the request/response loop -- independent
-from user requests. This allows to pre-compress CSS and JavaScript files and
-works just like the automatic compression with the ``{% compress %}`` tag.
+Django Compressor has the ability to run the compression "offline",
+i.e. outside of the request/response loop -- independent from user requests.
+If offline compression is enabled, no new files are generated during a request
+and the ``{% compress %}`` tag simply inserts links to the files in the
+offline cache (see :ref:`behind_the_scenes` for details). This results in better
+performance and enables certain deployment scenarios (see :ref:`scenarios`).
 
-To compress the files "offline" and update the offline cache you have
-to use the ``compress`` management command, ideally during deployment.
-Also make sure to enable the :attr:`django.conf.settings.COMPRESS_OFFLINE`
-setting. In case you don't use the ``compress`` management command, Django
-Compressor will automatically fallback to the automatic compression using
-the template tag.
+To use offline compression, enable the :attr:`django.conf.settings.COMPRESS_OFFLINE`
+setting and then run the ``compress`` management command to compress your assets
+and update the offline cache.
 
 The command parses all templates that can be found with the template
 loader (as specified in the TEMPLATE_LOADERS_ setting) and looks for
@@ -137,20 +137,18 @@ in the blocks, e.g.:
 
     {% load compress %}
     {% compress js %}
-    <script src="{{ path_to_files }}js/one.js" type="text/javascript" charset="utf-8"></script>
+    <script type="text/javascript">
+        alert("{{ greeting }}");
+    </script>
     {% endcompress %}
 
-Since this template requires a variable (``path_to_files``) you need to
-specify this in your settings before using the ``compress`` management
-command::
+Since this template requires a variable (``greeting``) you need to specify
+this in your settings before using the ``compress`` management command::
 
     COMPRESS_OFFLINE_CONTEXT = {
-        'path_to_files': '/static/js/',
+        'greeting': 'Hello there!',
     }
 
-If not specified, the ``COMPRESS_OFFLINE_CONTEXT`` will by default contain
-the commonly used setting to refer to saved files ``STATIC_URL``.
-
 The result of running the ``compress`` management command will be cached
 in a file called ``manifest.json`` using the :attr:`configured storage
 <django.conf.settings.COMPRESS_STORAGE>` to be able to be transferred from your development