Merge pull request #429 from totten/master-filesystem

framework/filesystem.md - Cleanup prose. Add table of `civicrm.files` subdirs.

docs/framework/filesystem.md

@@ -130,16 +130,19 @@ echo Civi::resources()->addScriptFile('civicrm.bower', 'jquery/dist/jquery.min.j
 
 ## Local data files
 
-CiviCRM also needs a files directory for storing a variety of site-specific
-files, including uploaded files, logs, and the template cache.  This directory
-is located away from the codebase in a location that is unlikely to be
-overwritten during upgrades.
+CiviCRM also needs a directory for storing volatile data files, such as 
+logs, caches, and uploads.  This directory is located outside
+the main codebase -- in a location that can be safely preserved during
+upgrades.
+
+This folder is generically referred to as `[civicrm.files]`, but the actual
+path is chosen to align with each CMS's conventions.
 
 ### Drupal and Backdrop
 
-CiviCRM stores its files in a folder named `civicrm` within the site-specific
-files directory.  This is commonly `sites/default/files/civicrm`, though it
-could be `files/civicrm`, `sites/example.org/files/civicrm`, or another
+CiviCRM stores its files in a folder named `civicrm` within the Drupal
+`files` directory.  This is commonly `sites/default/files/civicrm`, though
+it could be `files/civicrm`, `sites/example.org/files/civicrm`, or another
 folder determined by the system administrator.
 
 ### Joomla
@@ -152,6 +155,29 @@ Newly-installed CiviCRM sites on WordPress have their local files at
 `wp-content/uploads/civicrm`.  Many older sites use the previous default:
 `wp-content/plugins/files/civicrm`.
 
+### Tip: Sub-directories
+
+The `[civicrm.files]` is a base which contains several sub-directories.
+These folders include:
+
+
+| Code Name            | Typical Path                         | Recommended Access Level                        | Comments
+| -------------------- | ------------------------------------ | ----------------------------------------------- |-----------------------------------------------------------------
+| `configAndLogDir`    | `[civicrm.files]/ConfigAndLog`       | Prohibit all web access                         | Stores log files. Writes and reads should be infrequent, unless there are errors/warnings.
+| `customFileUploadDir` | `[civicrm.files]/custom`            | Prohibit all web access                         | Stores sensitive uploads (such as custom-field attachments). Writes and reads vary widely (depending on use-case/config).
+| `extensionsDir`      | `[civicrm.files]/ext`                | Allow file reads but prohibit directory listing | Stores downloaded extensions. Writes should be infrequent. Reads are very frequent. In hardened systems, this may be readonly or disabled.
+| `imageUploadDir`     | `[civicrm.files]/persist/contribute` | Allow file reads but prohibit directory listing | Stores uploaded or autogenerated media (images/css/etc). Writes and reads vary widely (depending on use-case/config).
+| `templateCompileDir` | `[civicrm.files]/templates_c`        | Prohibit all web access                         | Stores autogenerated PHP files. Writes should be infrequent. Reads are very frequent.
+| `uploadDir`          | `[civicrm.files]/upload`             | Prohibit all web access                         | Temporary files. Writes and reads vary widely (depending on use-case/config).
+
+!!! tip "Advanced filesystem and web server configurations"
+
+    Each folder has different requirements (with respect to permissions,
+    read-write frequency, etc).  Most Apache-based web servers respect the `.htaccess`
+    and `index.html` files, and these are configured automatically.
+    However, some web-servers don't support these, so CiviCRM's
+    status-check shows warnings if it detects unexpected configuration.
+
 ### Tip: Programmatic lookup
 
 If you are writing an extension or integration that needs to reference the