Updated several README files.

 - Legacy-Id: 9912

Author: levkowetz

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/static/README.rst ietf/README-BOWER.rstietf/static/README.rst renamed to 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
-visible location for ``ietf/static/bower.json``, a bower_ file which lists the
+The file ``bower.json`` in this direcory is a bower_ file which lists the
 external web assets used by the datatracker.
 
-In order to update the version of a component listed in
-``ietf/static/bower.json``, or add a new one, you should edit ``bower.json``,
-and then run the management command::
+In order to update the version of a component listed in ``ietf/bower.json``,
+or add a new one, you should edit ``bower.json``, and then run the management
+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
-differently than the rest: the ``lib/`` subdirectory holds distribution files for external
-client-side components, currently (18 Apr 2015) this means ``js`` and ``css`` components.
+This directory (``static/``) holds a number of subdirectories, where one is
+handled differently than the rest: the ``lib/`` subdirectory holds
+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
-name:
+These components each reside in their own subdirectory, which is named with
+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
-different versions, then any component upgrade which is accompanied by a change in template
-functionality will be have a long transition time during which the new pages are served with
-old components, with possible breakage.  We want to avoid this.
+If resources served over a CDN and/or with a high max-age don't have different
+URLs for different versions, then any component upgrade which is accompanied
+by a change in template functionality will be have a long transition time
+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 whole static directory should be copied to a location which is accessible under the
-URL given by STATIC_URL -- in production mode this URL contains the datatracker release
-version, which will let the CDN serve the static files which correspond to the current
-release.
+The intention is that after a release has been checked out, but before it is
+deployed, the whole static directory should be symlinked or copied to a
+location which is accessible under the URL given by STATIC_URL -- in
+production mode this URL contains the datatracker release version, which will
+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
-through a bower_ file; ``ietf/static/bower.json``.  In order to install a new
-version of a component, you should update the ``bower.json`` file, and then run the management
-command::
+With the exception of the ``pt*`` fonts and ``custom-bootstrap``, the
+components under ``static/lib/`` are managed through a bower_ file;
+``ietf/bower.json``.  In order to install a new version of a component, you
+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
-``bower.json`` (actually, it will do this for *all* ``bower.json`` files found in the
-``static/`` directories of all ``INSTALLED_APPS``), saving them temporarily under
-``.tmp/bower_components/``; it will then extract the relevant ``js`` and ``css`` files and
-place them in an appropriately named directory under ``static/lib/``.  The location
-used by ``bower_install`` is is controlled by ``COMPONENT_ROOT`` in ``settings.py``.
-
-Any datatracker-specific static files which should be served by the CDN rather than
-directly by the datatracker web server should be moved from under ``static/ to ``ietf/static/``,
-so that they will be collected by the ``ietf/manage.py collectstatic`` command and
-placed under `static/lib/`` from where they will be made available to the CDN.  Any
-template files referencing the files in question will need to be updated to use the
-``{% static 'foo/bar.jpg' %}`` notation to reference the files, so that the correct
-static url will be emitted.
+That command will fetch the required version of each external component listed
+in ``bower.json`` (actually, it will do this for *all* ``bower.json`` files
+found in all ``INSTALLED_APPS`` directories), saving them temporarily under
+``.tmp/bower_components/``; it will then extract the relevant ``js`` and
+``css`` files and place them in an appropriately named directory under
+``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 directly by the datatracker web server should be moved from under
+``static/`` to ``ietf/static/``, so that they will be collected by the
+``ietf/manage.py collectstatic`` command and placed under `static/lib/`` from
+where they will be made available to the CDN.  Any template files referencing
+the files in question will need to be updated to use the ``{% static
+'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/