Merge pull request #134 from agh1/viewing-log-files

Separate file system doc

docs/basics/filesystem.md

+# File system
+
+The file structure of the content management systems that CiviCRM operates in
+differs among the different content management systems it installs within, but
+the general concepts are the same.  One directory contains the CiviCRM
+**codebase** (including CMS-specific code to integrate with the website),
+another directory contains **local files** that are site-specific, and the site
+will have a CiviCRM **settings file**.
+
+## Codebase
+
+The codebase consists of the common CiviCRM code (found in the
+[civicrm-core](https://github.com/civicrm/civicrm-core/) and
+[civicrm-packages](https://github.com/civicrm/civicrm-packages/) repositories)
+along with the code to integrate with the CMS.  Obviously, Drupal and Backdrop
+modules, Joomla components, and WordPress plugins have different structures, so
+the [civicrm-drupal](https://github.com/civicrm/civicrm-drupal/),
+[civicrm-backdrop](https://github.com/civicrm/civicrm-backdrop/),
+[civicrm-joomla](https://github.com/civicrm/civicrm-joomla/), and
+[civicrm-wordpress](https://github.com/civicrm/civicrm-wordpress/) repositories
+contain the code connecting CiviCRM to the CMS along with some CMS-specific
+features.
+
+### Drupal and Backdrop
+
+The CiviCRM module is typically found in the `sites/all/modules/civicrm`
+directory.  As with any module, it is possible to have CiviCRM run from the
+`modules` directory within some other subdirectory of `sites` (for site-specific
+use), a subdirectory of either of these locations, or within the root `modules`
+directory (which is *not advisable*).
+
+The `sites/all/modules/civicrm/drupal` directory corresponds to the
+[civicrm-drupal](https://github.com/civicrm/civicrm-drupal/) repository.  It
+contains `civicrm.module`, the actual module file, along with the role sync
+modules, blocks, and drush and views integration.
+
+### Joomla
+
+CiviCRM's codebase exists in *two* places within Joomla:
+
+ -  A front-end component at `components/com_civicrm`
+ -  A back-end component at `administrator/components/com_civicrm`
+
+The back-end component contains the common CiviCRM code, in
+`administrator/components/com_civicrm/civicrm`.  The
+[civicrm-joomla](https://github.com/civicrm/civicrm-joomla/) repository contains
+a `site` directory for the front-end files and an `admin` directory for the
+back-end files.
+
+### WordPress
+
+The CiviCRM plugin is found in `wp-content/plugins/civicrm`.  This corresponds
+to the [civicrm-wordpress](https://github.com/civicrm/civicrm-wordpress/)
+repository, containing the plugin file as well as WP-CLI integration.  The
+common CiviCRM codebase is found at `wp-content/plugins/civicrm/civicrm`.
+
+## Local 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.
+
+### 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 `sites/example.org/files/civicrm` if such a folder exists.
+
+### Joomla
+
+The CiviCRM local files are within the `media/civicrm` directory.
+
+### WordPress
+
+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`.
+
+## Settings file
+
+CiviCRM's database connection, base URL, site key, CMS, and file paths are defined in `civicrm.settings.php`.
+
+### Drupal and Backdrop
+
+The `civicrm.settings.php` file will be a sibling of Drupal's `settings.php`,
+commonly at `sites/default/civicrm.settings.php`, or
+`sites/example.org/civicrm.settings.php` in multi-site.
+
+### Joomla
+
+There are two instances of `civicrm.settings.php` in Joomla, within each of the
+components:
+
+ -  front-end at `components/com_civicrm/civicrm.settings.php`
+ -  back-end at `administrator/components/com_civicrm/civicrm.settings.php`
+
+The files are *nearly* identical.  The one difference is that the front-end file
+has the site's normal base URL, while the back-end file has `/administrator/` on
+the end, pointing to the back-end of the site.
+
+### WordPress
+
+Newly-installed CiviCRM sites on WordPress have the settings file at
+`wp-content/uploads/civicrm/civicrm.settings.php`.  Many older sites, however,
+put the settings file within the CiviCRM plugin folder at
+`wp-content/plugins/civicrm/civicrm.settings.php`.  This latter location can be
+dangerous when upgrading: it is important in this case to keep the `civicrm`
+folder until the upgrade is complete and the site is verified to be working
+properly.

docs/dev-tools/debugging.md

@@ -50,11 +50,10 @@ A backtrace is a list of all the functions that were run in the execution of the
 
 ## Viewing log files
 
-CiviCRM's log files are stored in the `civicrm/ConfigAndLog` directory
-(below the `files` directory in Drupal sites, and below the `media`
-directory in Joomla sites and under `wp-content/plugins/files/` directory
-in Wordpress). Most runtime errors are logged here, as well as data that
-you explicitly write to log using the `CRM_Core_Error::debug log=true`
+CiviCRM's log files are stored in the `ConfigAndLog` directory within CiviCRM's
+local file storage (see [the File System documentation](../basics/filesystem.md)
+for details on your CMS).  Most runtime errors are logged here, as well as data
+that you explicitly write to log using the `CRM_Core_Error::debug log=true`
 parameter.
 
 
@@ -76,10 +75,10 @@ The following values can be added to your site's settings file `civicrm.settings
 - `define('CIVICRM_CONTAINER_CACHE', 'never');` causes Civi to rebuild the [container](http://symfony.com/doc/current/service_container.html) from the latest data on every page-load
 
 !!! tip
-    When any sort of "logging stuff to a file" is enabled by one of the above settings, check the following directories for the resulting file:
-
-    - Drupal: `files/civicrm/ConfigAndLog/`
-    - Joomla: `media/civicrm/ConfigAndLog/`
+    When any sort of "logging stuff to a file" is enabled by one of the
+    above settings, check the `ConfigAndLog` directory within the local files
+    directory to find the log.  (See [the File System
+    documentation](../basics/filesystem.md) for the location in your CMS.)
 
 
 ## Viewing a query log from MySQL
@@ -94,12 +93,12 @@ The relevant settings are:
     general_log_file=/tmp/mysql.log
     # Enable/disable the query log
     general_log=1
-    
+
 You can enable the query log at runtime via SQL, provided the path to the logfile is configured.
 
     SET GLOBAL general_log = 'ON';
     SET GLOBAL general_log = 'OFF';
-    
+
 And you can inspect the query log settings also:
 
     mysql> show variables like '%general%';

mkdocs.yml

@@ -29,6 +29,7 @@ pages:
   - Developer Community: basics/community.md    # page-tree = DONE
   - Useful Skills: basics/skills.md       # page-tree = DONE
   - Planning Your Project: basics/planning.md   # page-tree = DONE
+  - File System: basics/filesystem.md
   # buildkit: /setup/buildkit.md                # page-tree = NEED_NEW_PAGE  # summary: See Github README for download instructions. Alternatively, follow links and install particular tools as-needed.
   - Debugging: dev-tools/debugging.md           # page-tree = NEED_PAGE_MOVE to /setup/debugging.md
 - Core Development: