Updated several README files.

- Legacy-Id: 9912

bootstrap/README-DATATRACKER.rst

@@ -4,7 +4,7 @@ _______________________
 Content
 =======
 
-The files in this directory are modified versions of bootstrap v3.3.4.  This is
+The files in this directory are modified versions of bootstrap_.  This is
 a cumbersome way to customize bootsrap, but as of the time of writing this
 (03 Apr 2015), there seems to be no provision for including modifications
 within the distributed build environment without either editing files in
@@ -102,3 +102,4 @@ and more. Requires Jekyll. Usually only necessary if you're hacking on
 Bootstrap itself.
 
 
+.. _bootstrap: http://getbootstrap.com

ietf/README-BOWER.rst

@@ -1,13 +1,12 @@
 Handling of External Javascript and CSS Components 
 ==================================================
 
-This directory (``ietf/static/``) exists for the sole purpose of providing a
+The file ``bower.json`` in this direcory is a bower_ file which lists the
-visible location for ``ietf/static/bower.json``, a bower_ file which lists the
 external web assets used by the datatracker.
 
-In order to update the version of a component listed in
+In order to update the version of a component listed in ``ietf/bower.json``,
-``ietf/static/bower.json``, or add a new one, you should edit ``bower.json``,
+or add a new one, you should edit ``bower.json``, and then run the management
-and then run the management command::
+command::
 
     $ ietf/manage.py bower_install
 
@@ -26,7 +25,9 @@ management command.)
 The ``bower_install`` command is not run automatically by ``bin/mkrelease``,
 since it needs an updated ``bower.json`` in order to do anything interesting;
 and we're not running ``bower update`` since some package releases break
-compatibility.  So when you're intending to 
+compatibility.  So when you're intending to update an external web asset to a
-
+newer version, you need to edit the ``bower.json`` file, run ``manage.py
+bower_install``, verify that the new version doesn't break things, and then
+commit the new files under ``static\lib\`` and the updated ``bower.json``.
 
 .. _bower: http://bower.io/

static/README.rst

@@ -1,17 +1,20 @@
 Handling of External Javascript and CSS Components 
 ==================================================
 
-This directory (``static/``) holds a number of subdirectories, where one is handled
+This directory (``static/``) holds a number of subdirectories, where one is
-differently than the rest: the ``lib/`` subdirectory holds distribution files for external
+handled differently than the rest: the ``lib/`` subdirectory holds
-client-side components, currently (18 Apr 2015) this means ``js`` and ``css`` components.
+distribution files for external client-side components, currently (28 Jul
+2015) this means ``js`` and ``css`` components and fonts.
 
-These components each reside in their own subdirectory, which is named with the component
+These components each reside in their own subdirectory, which is named with
-name:
+the component name:
 
     henrik@zinfandel $ ls -l static/lib
-    total 44
+    total 52
+    drwxr-xr-x 5 henrik henrik 4096 Jul 26 08:55 admin
     drwxr-xr-x 6 henrik henrik 4096 Jul 25 15:25 bootstrap
     drwxr-xr-x 4 henrik henrik 4096 Jul 25 15:25 bootstrap-datepicker
+    drwxr-xr-x 5 henrik henrik 4096 Jul 28 02:39 custom-bootstrap
     drwxr-xr-x 4 henrik henrik 4096 Jul 25 15:25 font-awesome
     drwxr-xr-x 2 henrik henrik 4096 Jul 25 15:25 jquery
     drwxr-xr-x 2 henrik henrik 4096 Jul 25 15:25 jquery.cookie
@@ -20,38 +23,42 @@ name:
     drwxr-xr-x 2 henrik henrik 4096 Jul 25 15:24 ptserif
     drwxr-xr-x 2 henrik henrik 4096 Jul 25 15:25 select2
     drwxr-xr-x 2 henrik henrik 4096 Jul 25 15:25 select2-bootstrap-css
+    drwxrwxrwx 3 henrik henrik 4096 Jul 27 11:42 static
 
-If resources served over a CDN and/or with a high max-age don't have different URLs for
+If resources served over a CDN and/or with a high max-age don't have different
-different versions, then any component upgrade which is accompanied by a change in template
+URLs for different versions, then any component upgrade which is accompanied
-functionality will be have a long transition time during which the new pages are served with
+by a change in template functionality will be have a long transition time
-old components, with possible breakage.  We want to avoid this.
+during which the new pages are served with old components, with possible
+breakage.  We want to avoid this.
 
-The intention is that after a release has been checked out, but before it is deployed,
+The intention is that after a release has been checked out, but before it is
-the whole static directory should be copied to a location which is accessible under the
+deployed, the whole static directory should be symlinked or copied to a
-URL given by STATIC_URL -- in production mode this URL contains the datatracker release
+location which is accessible under the URL given by STATIC_URL -- in
-version, which will let the CDN serve the static files which correspond to the current
+production mode this URL contains the datatracker release version, which will
-release.
+let the CDN serve the static files which correspond to the current release.
 
-With the exception of the ``pt*`` fonts, all components under ``static/lib/`` are managed
+With the exception of the ``pt*`` fonts and ``custom-bootstrap``, the
-through a bower_ file; ``ietf/static/bower.json``.  In order to install a new
+components under ``static/lib/`` are managed through a bower_ file;
-version of a component, you should update the ``bower.json`` file, and then run the management
+``ietf/bower.json``.  In order to install a new version of a component, you
-command::
+should update the ``bower.json`` file, and then run the management command::
 
     $ ietf/manage.py bower_install
 
-That command will fetch the required version of each external component listed in
+That command will fetch the required version of each external component listed
-``bower.json`` (actually, it will do this for *all* ``bower.json`` files found in the
+in ``bower.json`` (actually, it will do this for *all* ``bower.json`` files
-``static/`` directories of all ``INSTALLED_APPS``), saving them temporarily under
+found in all ``INSTALLED_APPS`` directories), saving them temporarily under
-``.tmp/bower_components/``; it will then extract the relevant ``js`` and ``css`` files and
+``.tmp/bower_components/``; it will then extract the relevant ``js`` and
-place them in an appropriately named directory under ``static/lib/``.  The location
+``css`` files and place them in an appropriately named directory under
-used by ``bower_install`` is is controlled by ``COMPONENT_ROOT`` in ``settings.py``.
+``static/lib/``.  The location used by ``bower_install`` is controlled by the
+``COMPONENT_ROOT`` setting in ``settings.py``.
 
-Any datatracker-specific static files which should be served by the CDN rather than
+Any datatracker-specific static files which should be served by the CDN rather
-directly by the datatracker web server should be moved from under ``static/ to ``ietf/static/``,
+than directly by the datatracker web server should be moved from under
-so that they will be collected by the ``ietf/manage.py collectstatic`` command and
+``static/`` to ``ietf/static/``, so that they will be collected by the
-placed under `static/lib/`` from where they will be made available to the CDN.  Any
+``ietf/manage.py collectstatic`` command and placed under `static/lib/`` from
-template files referencing the files in question will need to be updated to use the
+where they will be made available to the CDN.  Any template files referencing
-``{% static 'foo/bar.jpg' %}`` notation to reference the files, so that the correct
+the files in question will need to be updated to use the ``{% static
-static url will be emitted.
+'foo/bar.jpg' %}`` notation to reference the files, so that the correct static
+url will be emitted both in production and development mode.
 
 .. _bower: http://bower.io/