5 files changed, 109 insertions, 24 deletions
diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index d6bc8cbb8..fc02b3f7d 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -512,6 +512,93 @@ time at start up as a cachebust token:
 .. index::
    single: static assets view
 
+CSS and JavaScript source and cache busting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Often one needs to refer to images and other static assets inside CSS and
+JavaScript files. If cache busting is active, the final static asset URL is
+not available until the static assets have been assembled. These URLs cannot
+be handwritten. Thus, when having static asset references in CSS and
+JavaScript, one needs to perform one of the following tasks.
+
+* Process the files by using a precompiler which rewrites URLs to their final
+  cache busted form.
+
+* Templatize JS and CSS, and call ``request.static_url()`` inside their
+  template code.
+
+* Pass static URL references to CSS and JavaScript via other means.
+
+Below are some simple approaches for CSS and JS programming which consider
+asset cache busting. These approaches do not require additional tools or
+packages.
+
+Relative cache busted URLs in CSS
++++++++++++++++++++++++++++++++++
+
+Consider a CSS file ``/static/theme/css/site.css`` which contains the
+following CSS code.
+
+.. code-block:: css
+
+    body {
+        background: url(/static/theme/img/background.jpg);
+    }
+
+Any changes to ``background.jpg`` would not appear to the visitor because the
+URL path is not cache busted as it is. Instead we would have to construct an
+URL to the background image with the default ``PathSegmentCacheBuster`` cache
+busting mechanism::
+
+    https://site/static/1eeb262c717/theme/img/background.jpg
+
+Every time the image is updated, the URL would need to be changed. It is not
+practical to write this non-human readable URL into a CSS file.
+
+However, the CSS file itself is cache busted and is located under the path for
+static assets. This lets us use relative references in our CSS to cache bust
+the image.
+
+.. code-block:: css
+
+    body {
+        background: url(../img/background.jpg);
+    }
+
+The browser would interpret this as having the CSS file hash in URL::
+
+    https://site/static/ab234b262c71/theme/css/../img/background.jpg
+
+The downside of this approach is that if the background image changes, one
+needs to bump the CSS file. The CSS file hash change signals the caches that
+the relative URL to the image in the CSS has been changed. When updating CSS
+and related image assets, updates usually happen hand in hand, so this does
+not add extra effort to theming workflow.
+
+Passing cache busted URLs to JavaScript
++++++++++++++++++++++++++++++++++++++++
+
+For JavaScript, one can pass static asset URLs as function arguments or
+globals. The globals can be generated in page template code, having access to
+the ``request.static_url()`` function.
+
+Below is a simple example of passing a cached busted image URL in the Jinja2
+template language. Put the following code into the ``<head>`` section of the
+relevant page.
+
+.. code-block:: html
+
+    <script>
+        window.assets.backgroundImage =
+            "{{ '/theme/img/background.jpg'|static_url() }}";
+    </script>
+
+Then in your main ``site.js`` file put the following code.
+
+.. code-block:: javascript
+
+    var image = new Image(window.assets.backgroundImage);
+
 .. _advanced_static:
 
 Advanced: Serving Static Assets Using a View Callable
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index fc5ae6dc6..46b2c4f76 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -119,7 +119,7 @@ Non-Predicate Arguments
 ``renderer``
   Denotes the :term:`renderer` implementation which will be used to construct
   a :term:`response` from the associated view callable's return value.
-  
+
   .. seealso:: See also :ref:`renderers_chapter`.
 
   This is either a single string term (e.g. ``json``) or a string implying a
@@ -1020,7 +1020,7 @@ there's a ``should_cache`` GET or POST variable:
    @view_config(http_cache=3600)
    def view(request):
        response = Response()
-       if not 'should_cache' in request.params:
+       if 'should_cache' not in request.params:
            response.cache_control.prevent_auto = True
        return response
 
diff --git a/docs/quick_tutorial/debugtoolbar.rst b/docs/quick_tutorial/debugtoolbar.rst
index a5623ae2a..f11abc493 100644
--- a/docs/quick_tutorial/debugtoolbar.rst
+++ b/docs/quick_tutorial/debugtoolbar.rst
@@ -89,24 +89,24 @@ temporarily.
 Extra Credit
 ============
 
-# Why don't we add ``pyramid_debugtoolbar`` to the list of
-  ``install_requires`` dependencies in ``debugtoolbar/setup.py``?
+#. Why don't we add ``pyramid_debugtoolbar`` to the list of
+   ``install_requires`` dependencies in ``debugtoolbar/setup.py``?
 
-# Introduce a bug into your application:  Change:
+#. Introduce a bug into your application:  Change:
 
-  .. code-block:: python
+   .. code-block:: python
 
-    def hello_world(request):
-        return Response('<body><h1>Hello World!</h1></body>')
+     def hello_world(request):
+         return Response('<body><h1>Hello World!</h1></body>')
 
-  to:
+   to:
 
-  .. code-block:: python
+   .. code-block:: python
 
     def hello_world(request):
         return xResponse('<body><h1>Hello World!</h1></body>')
 
-  Save, and visit http://localhost:6543/ again.  Notice the nice
-  traceback display.  On the lowest line, click the "screen" icon to the
-  right, and try typing the variable names ``request`` and ``Response``.
-  What else can you discover?
+   Save, and visit http://localhost:6543/ again.  Notice the nice
+   traceback display.  On the lowest line, click the "screen" icon to the
+   right, and try typing the variable names ``request`` and ``Response``.
+   What else can you discover?
diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst
index 4e062e575..36942c767 100644
--- a/docs/quick_tutorial/ini.rst
+++ b/docs/quick_tutorial/ini.rst
@@ -131,6 +131,8 @@ Extra Credit
 #. The entry point in ``setup.py`` didn't mention ``__init__.py`` when
    it declared ``tutorial:main`` function. Why not?
 
+#. What is the purpose of ``**settings``? What does the ``**`` signify?
+
 .. seealso::
    :ref:`project_narr`,
    :ref:`scaffolding_chapter`,
@@ -138,7 +140,3 @@ Extra Credit
    :ref:`environment_chapter`,
    :ref:`paste_chapter`
 
-Extra Credit
-============
-
-#. What is the purpose of ``**settings``? What does the ``**`` signify?
diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst
index d2ad7a9ca..1d810b05b 100644
--- a/docs/tutorials/wiki2/authorization.rst
+++ b/docs/tutorials/wiki2/authorization.rst
@@ -5,12 +5,12 @@ Adding authorization
 ====================
 
 :app:`Pyramid` provides facilities for :term:`authentication` and
-::term:`authorization`.  We'll make use of both features to provide security
-:to our application.  Our application currently allows anyone with access to
-:the server to view, edit, and add pages to our wiki.  We'll change that to
-:allow only people who are members of a *group* named ``group:editors`` to add
-:and edit wiki pages but we'll continue allowing anyone with access to the
-:server to view pages.
+:term:`authorization`.  We'll make use of both features to provide security
+to our application.  Our application currently allows anyone with access to
+the server to view, edit, and add pages to our wiki.  We'll change that to
+allow only people who are members of a *group* named ``group:editors`` to add
+and edit wiki pages but we'll continue allowing anyone with access to the
+server to view pages.
 
 We will also add a login page and a logout link on all the pages.  The login
 page will be shown when a user is denied access to any of the views that