From 8cf43a546fe292b212cbd853c0b67219f31d3460 Mon Sep 17 00:00:00 2001
From: Nicolas Giard <github@ngpixel.com>
Date: Mon, 25 Apr 2022 17:23:08 -0400
Subject: [PATCH] docs: reformat README

---
 README.md | 73 ++++++++++++-------------------------------------------
 1 file changed, 15 insertions(+), 58 deletions(-)

diff --git a/README.md b/README.md
index 217695f5a..0e4e69b27 100644
--- a/README.md
+++ b/README.md
@@ -95,68 +95,39 @@ This will create packages under `ietf/static/dist/ietf`, which are then served b
 
 The "new" datatracker uses Twitter Bootstrap for the UI.
 
-Get familiar with <https://getbootstrap.com/getting-started/> and use
-those UI elements, CSS classes, etc. instead of cooking up your own.
+Get familiar with <https://getbootstrap.com/getting-started/> and use those UI elements, CSS classes, etc. instead of cooking up your own.
 
 Some ground rules:
 
--   Think hard before tweaking the bootstrap CSS, it will make it harder
-    to upgrade to future releases.
--   No `<style>` tags in the HTML! Put CSS into the "morecss" block of
-    a template instead.
--   CSS that is used by multiple templates goes into static/css/ietf.css
-    or a new CSS file.
--   Javascript that is only used on one template goes into the "js"
-    block of that template.
--   Javascript that is used by multiple templates goes into
-    static/js/ietf.js or a new js file.
+-   Think hard before tweaking the bootstrap CSS, it will make it harder to upgrade to future releases.
+-   No `<style>` tags in the HTML! Put CSS into the "morecss" block of a template instead.
+-   CSS that is used by multiple templates goes into static/css/ietf.css or a new CSS file.
+-   Javascript that is only used on one template goes into the "js" block of that template.
+-   Javascript that is used by multiple templates goes into static/js/ietf.js or a new js file.
 -   Avoid CSS, HTML styling or Javascript in the python code!
 
 #### Serving Static Files via CDN
 
 ##### Production Mode
 
-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 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 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 standard django `collectstatic` management command
-will be run, resulting in all static files being collected from their
-working directory location and placed in an appropriate location for
-serving via CDN. This location will have the datatracker release version
-as part of its URL, so that after the deployment of a new release, the
-CDN will be forced to fetch the appropriate static files for that
-release.
+The intention is that after a release has been checked out, but before it is deployed, the standard django `collectstatic` management command will be run, resulting in all static files being collected from their working directory location and placed in an appropriate location for serving via CDN. This location will have the datatracker release version as part of its URL, so that after the deployment of a new release, the CDN will be forced to fetch the appropriate static files for that release.
 
-An important part of this is to set up the `STATIC_ROOT` and
-`STATIC_URL` settings appropriately. In 6.4.0, the setting is as follows
-in production mode:
+An important part of this is to set up the `STATIC_ROOT` and `STATIC_URL` settings appropriately. In 6.4.0, the setting is as follows in production mode:
 
 ```
 STATIC_URL = "https://www.ietf.org/lib/dt/%s/"%__version__
 STATIC_ROOT = CDN_ROOT + "/a/www/www6s/lib/dt/%s/"%__version__
 ```
 
-The result is that all static files collected via the `collectstatic`
-command will be placed in a location served via CDN, with the release
-version being part of the URL.
+The result is that all static files collected via the `collectstatic` command will be placed in a location served via CDN, with the release version being part of the URL.
 
 ##### Development Mode
 
-In development mode, `STATIC_URL` is set to `/static/`, and Django's
-`staticfiles` infrastructure makes the static files available under that
-local URL root (unless you set
-`settings.SERVE_CDN_FILES_LOCALLY_IN_DEV_MODE` to `False`). It is not
-necessary to actually populate the `static/` directory by running
-`collectstatic` in order for static files to be served when running
-`ietf/manage.py runserver` -- the `runserver` command has extra support
-for finding and serving static files without running collectstatic.
+In development mode, `STATIC_URL` is set to `/static/`, and Django's `staticfiles` infrastructure makes the static files available under that local URL root (unless you set `settings.SERVE_CDN_FILES_LOCALLY_IN_DEV_MODE` to `False`). It is not necessary to actually populate the `static/` directory by running `collectstatic` in order for static files to be served when running `ietf/manage.py runserver` -- the `runserver` command has extra support for finding and serving static files without running collectstatic.
 
-In order to work backwards from a file served in development mode to the
-location from which it is served, the mapping is as follows:
+In order to work backwards from a file served in development mode to the location from which it is served, the mapping is as follows:
 
 | Development URL | Working copy location |
 | --------------- | --------------------- |
@@ -165,29 +136,15 @@ location from which it is served, the mapping is as follows:
 
 #### Handling of External Javascript and CSS Components
 
-In order to make it easy to keep track of and upgrade external
-components, these are now handled by a tool called `npm` via the
-configuration in `package.json`.
+In order to make it easy to keep track of and upgrade external components, these are now handled by a tool called `yarn` via the configuration in `package.json`.
 
 #### Handling of Internal Static Files
 
-Previous to this release, internal static files were located under
-`static/`, mixed together with the external components. They are now
-located under `ietf/static/ietf/` and `ietf/secr/static/secr`, and will
-be collected for serving via CDN by the `collectstatic` command. Any
-static files associated with a particular app will be handled the same
-way (which means that all `admin/` static files automatically will be
-handled correctly, too).
+Previous to this release, internal static files were located under `static/`, mixed together with the external components. They are now located under `ietf/static/ietf/` and `ietf/secr/static/secr`, and will be collected for serving via CDN by the `collectstatic` command. Any static files associated with a particular app will be handled the same way (which means that all `admin/` static files automatically will be handled correctly, too).
 
 #### Changes to Template Files
 
-In order to make the template files refer to the correct versioned CDN
-URL (as given by the STATIC_URL root) all references to static files in
-the templates have been updated to use the `static` template tag when
-referring to static files. This will automatically result in both
-serving static files from the right place in development mode, and
-referring to the correct versioned URL in production mode and the
-simpler `/static/` URLs in development mode.
+In order to make the template files refer to the correct versioned CDN URL (as given by the STATIC_URL root) all references to static files in the templates have been updated to use the `static` template tag when referring to static files. This will automatically result in both serving static files from the right place in development mode, and referring to the correct versioned URL in production mode and the simpler `/static/` URLs in development mode.
 
 #### Deployment