- Patch #952606 by jhodgdon: INSTALL.txt needs correction and clarification.

1 files changed, 228 insertions, 225 deletions

diff --git a/INSTALL.txt b/INSTALL.txt
index 180161b0d..fe017c8ec 100644
--- a/INSTALL.txt
+++ b/INSTALL.txt
@@ -3,21 +3,21 @@
 CONTENTS OF THIS FILE
 ---------------------
 
- * Requirements
- * Optional tasks
+ * Requirements and notes
+ * Optional server requirements
  * Installation
- * Drupal administration
- * Customizing your theme(s)
+ * Building and customizing your site
  * Multisite configuration
  * More information
 
-REQUIREMENTS
-------------
+
+REQUIREMENTS AND NOTES
+----------------------
 
 Drupal requires:
 
 - A web server. Apache (version 2.0 or greater) is recommended.
-- PHP 5.2.0 (or greater) (http://www.php.net/).
+- PHP 5.2.4 (or greater) (http://www.php.net/).
 - One of the following databases:
   - MySQL 5.0.15 (or greater) (http://www.mysql.com/).
   - MariaDB 5.1.44 (or greater) (http://mariadb.org/). MariaDB is a fully
@@ -29,296 +29,296 @@ For more detailed information about Drupal requirements, including a list of
 PHP extensions and configurations that are required, see "System requirements"
 (http://drupal.org/requirements) in the Drupal handbook.
 
-For detailed information on how to configure a test server environment using
-a variety of operating systems and web servers, see "Local server setup"
+For detailed information on how to configure a test server environment using a
+variety of operating systems and web servers, see "Local server setup"
 (http://drupal.org/node/157602) in the Drupal handbook.
 
-OPTIONAL TASKS
---------------
+Note that all directories mentioned in this document are always relative to the
+directory of your Drupal installation, and commands are meant to be run from
+this directory (except for the initial commands that create that directory).
 
-- To use XML-based services such as the Blogger API and RSS syndication,
-  you will need PHP's XML extension. This extension is enabled by default.
 
-- To use Drupal's "Clean URLs" feature on an Apache web server, you will need
-  the mod_rewrite module and the ability to use local .htaccess files. For
-  Clean URLs support on IIS, see "Using Clean URLs with IIS"
+OPTIONAL SERVER REQUIREMENTS
+----------------------------
+
+- If you want to use Drupal's "Clean URLs" feature on an Apache web server, you
+  will need the mod_rewrite module and the ability to use local .htaccess
+  files. For Clean URLs support on IIS, see "Using Clean URLs with IIS"
   (http://drupal.org/node/3854) in the Drupal handbook.
 
+- If you plan to use XML-based services such as RSS aggregation, you will need
+  PHP's XML extension. This extension is enabled by default on most PHP
+  installations.
+
 - To serve gzip compressed CSS and JS files on an Apache web server, you will
   need the mod_headers module and the ability to use local .htaccess files.
 
-- Various Drupal features require that the web server process (for
-  example, httpd) be able to initiate outbound connections. This is usually
-  possible, but some hosting providers or server configurations forbid such
-  connections. The features that depend on this functionality include the
-  integrated "Update status" module (which downloads information about
-  available updates of Drupal core and any installed contributed modules and
-  themes), the ability to log in via OpenID, fetching aggregator feeds, or
-  other network-dependent services.
+- Some Drupal functionality (e.g., checking whether Drupal and contributed
+  modules need updates, RSS aggregation, etc.) require that the web server be
+  able to go out to the web and download information. If you want to use this
+  functionality, you need to verify that your hosting provider or server
+  configuration allows the web server to initiate outbound connections. Most web
+  hosting setups allow this.
 
 
 INSTALLATION
 ------------
 
-1. DOWNLOAD DRUPAL AND OPTIONALLY A TRANSLATION
+1. Download and extract Drupal.
 
-   You can obtain the latest Drupal release from http://drupal.org/. The files
-   are in .tar.gz format and can be extracted using most compression tools. On a
-   typical Unix command line, use:
+   You can obtain the latest Drupal release from http://drupal.org -- the files
+   are in .tar.gz format and can be extracted using most compression tools.
 
-     wget http://drupal.org/files/projects/drupal-x.x.tar.gz
-     tar -zxvf drupal-x.x.tar.gz
+   To download and extract the files, on a typical Unix/Linux command line, use
+   the following commands (assuming you want version x.y of Drupal):
 
-   This will create a new directory drupal-x.x/ containing all Drupal files
-   and directories. Move the contents of that directory into a directory within
-   your web server's document root or your public HTML directory:
+     wget http://drupal.org/files/projects/drupal-x.y.tar.gz
+     tar -zxvf drupal-x.y.tar.gz
 
-     mv drupal-x.x/* drupal-x.x/.htaccess /var/www/html
+   This will create a new directory drupal-x.y/ containing all Drupal files and
+   directories. Then, to move the contents of that directory into a directory
+   within your web server's document root or your public HTML directory,
+   continue with this command:
+
+     mv drupal-x.y/* drupal-x.y/.htaccess /path/to/your/installation
+
+2. Optionally, download a translation.
 
    By default, Drupal is installed in English, and further languages may be
-   installed later. Follow these steps to translate Drupal into your language
-   during installation:
+   installed later. If you prefer to install Drupal in another language
+   initially:
 
-   - Download a translation file for this Drupal version from the translation
-     server:
-     http://localize.drupal.org/download
+   - Download a translation file for the correct Drupal version and language
+     from the translation server: http://localize.drupal.org/download
 
    - Rename the downloaded file to your language's ISO code (e.g., de.po or
-     fr.po) and place it into the directory /translations right below
-     the installation profile's directory that you want to use for your
-     installation (usually "standard"):
+     fr.po) and place it into your installation profile's translations
+     directory. For instance, if you are using the Standard install profile,
+     move the .po file into the directory:
 
-       /profiles/standard/translations/
+       profiles/standard/translations/
 
-   - Reload the language selection page after adding translations.
+   For detailed instructions, visit http://drupal.org/localize
 
-   For detailed instructions, visit http://drupal.org/localize.
+3. Create the Drupal database.
 
-2. IF NECESSARY, CREATE THE CONFIGURATION FILE AND GRANT WRITE PERMISSIONS
+   Because Drupal stores all site information in a database, you must create
+   this database in order to install Drupal, and grant Drupal certain database
+   privileges (such as the ability to create tables). For details, consult
+   INSTALL.mysql.txt, INSTALL.pgsql.txt, or INSTALL.sqlite.txt. You may also
+   need to consult your web hosting provider for instructions specific to your
+   web host.
 
-   Drupal comes with a default.settings.php file in the sites/default
-   directory. The installer uses this file as a template to create your
-   settings file using the details you provide through the install process.
-   To avoid problems when upgrading, Drupal is not packaged with an actual
-   settings file. During installation, Drupal will try to create this settings
-   file automatically. If this fails (which it can due to different server
-   setups), you must create a file named settings.php yourself. You may do so
-   by making a copy of default.settings.php (or create an empty file with
-   this name in the same directory). For example, (from the installation
-   directory) make a copy of the default.settings.php file with the command:
+   Take note of the username, password, database name, and hostname as you
+   create the database. You will enter this information during the install.
 
-     cp sites/default/default.settings.php sites/default/settings.php
+4. Make the sites/default directory writable.
 
-   Next, give the web server write privileges to the sites/default/settings.php
-   file with the command (from the installation directory):
+   During installation, several files and directories need to be created, which
+   the installation script can do automatically if the web server has write
+   permission on the sites/default directory. If you are creating a multisite
+   installation, substitute the correct sites directory for sites/default (see
+   the Multisite Configuration section of this file, below).
 
-     chmod o+w sites/default/settings.php
+   For example, on a Unix/Linux command line, you can grant everyone (including
+   the web server) permission to write to the sites/default directory with this
+   command:
 
-  So that the files directory can be created automatically, give the web server
-  write privileges to the sites/default directory with the command (from the
-  installation directory):
+      chmod a+w sites/default
 
-     chmod o+w sites/default
+   Be sure to set the permissions back after the installation is finished!
+   Sample command:
 
-3. CREATE THE DRUPAL DATABASE
+      chmod go-w sites/default
 
-   Drupal requires access to a database in order to be installed. Your database
-   user will need sufficient privileges to run Drupal. Additional information
-   about privileges, and instructions to create a database using the command
-   line are available in INSTALL.mysql.txt (for MySQL) or INSTALL.pgsql.txt
-   (for PostgreSQL).
+5. Run the install script.
 
-   To create a database using PHPMyAdmin or a web-based control panel consult
-   the documentation or ask your webhost service provider.
+   To run the install script point your browser to the base URL of your website
+   (e.g., http://www.example.com).
 
-   Take note of the username, password, database name and hostname as you
-   create the database. You will enter these items in the install script.
+   You will be guided through several screens to set up the database, add the
+   site maintenance account (the first user, also known as user/1), and provide
+   basic web site settings.
 
-4. RUN THE INSTALL SCRIPT
+   The install script may also tell you that it cannot proceed until you fix
+   certain issues with server requirements and files. The most common file
+   system issues are with write permissions on directories and files:
 
-   To run the install script point your browser to the base URL of your website
-   (e.g., http://www.example.com).
+   a. Missing settings.php file.
 
-   You will be guided through several screens to set up the database,
-   create tables, add the site maintenance account (the first user, also known
-   as user/1), and provide basic web site settings.
+      Drupal will try to automatically create a settings.php configuration file,
+      which is normally in the directory sites/default (to avoid problems when
+      upgrading, Drupal is not packaged with this file). If auto-creation fails,
+      and you followed step 4 above, you can create this file yourself, using
+      the file sites/default/default.settings.php as a template.
 
-   The install script will attempt to create a files storage directory
-   in the default location at sites/default/files (the location of the
-   files directory may be changed after Drupal is installed). In some
-   cases, you may need to create the directory and modify its permissions
-   manually. Use the following commands (from the installation directory)
-   to create the public and private files directories and grant the web server
-   write privileges to them:
+      For example, on a Unix/Linux command line, you can make a copy of the
+      default.settings.php file with the command:
 
-     mkdir sites/default/files
-     chmod o+w sites/default/files
-     mkdir sites/default/private
-     chmod o+w sites/default/private
+        cp sites/default/default.settings.php sites/default/settings.php
 
-   The install script will attempt to write-protect the settings.php file and
-   the sites/default directory after saving your configuration. However, you
-   may need to manually write-protect them using the commands (from the
-   installation directory):
+      Next, grant write privileges to the file to everyone (including the web
+      server) with the command:
 
-     chmod a-w sites/default/settings.php
-     chmod a-w sites/default
+        chmod a+w sites/default/settings.php
 
-   If you make manual changes to the file later, be sure to protect it again
-   after making your modifications. Failure to remove write permissions to that
-   file is a security risk. Although the default location for the settings.php
-   file is at sites/default/settings.php, it may be in another location
-   if you use the multi-site setup, as explained below.
+      Be sure to set the permissions back after the installation is finished!
+      Sample command:
 
-5. CONFIGURE DRUPAL
+        chmod go-w sites/default/settings.php
 
-   When the install script succeeds, you will be directed to the "Welcome"
-   page logged in with the site maintenance account. Proceed with the initial
-   configuration steps suggested on the "Welcome" page.
+   b. Files directory.
 
-   If the default Drupal theme is not displaying properly and links on the page
-   result in "Page Not Found" errors, try manually setting the $base_url variable
-   in the settings.php file if not already set. It's currently known that servers
-   running FastCGI can run into problems if the $base_url variable is left
-   commented out (see http://bugs.php.net/bug.php?id=19656).
+      The install script will attempt to create a files storage directory in the
+      default location at sites/default/files (the location of the files
+      directory may be changed after Drupal is installed). If auto-creation
+      fails, and you followed step 4 above, you can create this directory
+      yourself. You will also need to grant the web server write permission on
+      this directory. Sample commands from a Unix/Linux command line:
 
-6. REVIEW FILE SYSTEM STORAGE SETTINGS AND FILE PERMISSIONS
+        mkdir sites/default/files
+        chmod a+w sites/default/files
 
-   The files directory created in step 4 is the default file system path used
-   to store all uploaded files, as well as some temporary files created by Drupal.
-   After installation, the settings for the file system path may be modified
-   to store uploaded files in a different location.
+   c. Write permissions after install.
 
-   It is not necessary to modify this path, but you may wish to change it if:
+      The install script will attempt to write-protect the settings.php file and
+      the sites/default directory after saving your configuration. If this
+      fails, you will be notified, and you can do it manually. Sample commands
+      from a Unix/Linux command line:
 
-     * your site runs multiple Drupal installations from a single codebase
-       (modify the file system path of each installation to a different
-       directory so that uploads do not overlap between installations); or,
+        chmod go-w sites/default/settings.php
+        chmod go-w sites/default
 
-     * your site runs a number of web server front-ends behind a load
-       balancer or reverse proxy (modify the file system path on each
-       server to point to a shared file repository).
+6. Verify that the site is working.
 
-   To modify the file system path:
+   When the install script finishes, you will be logged in with the site
+   maintenance account on a "Welcome" page. If the default Drupal theme is not
+   displaying properly and links on the page result in "Page Not Found" errors,
+   you may be experiencing problems with clean URLs. Visit
+   http://drupal.org/getting-started/clean-urls to troubleshoot.
 
-     * Ensure that the new location for the path exists or create it if
-       necessary. To create a new directory named uploads, for example,
-       use the following command from a shell or system prompt (while in
-       the installation directory):
+7. Change file system storage settings (optional).
 
-           mkdir uploads
+   The files directory created in step 5 is the default file system path used to
+   store all uploaded files, as well as some temporary files created by
+   Drupal. After installation, you can modify the file system path to store
+   uploaded files in a different location.
 
-     * Ensure that the new location for the path is writable by the web
-       server process. To grant write permissions for a directory named
-       uploads, you may need to use the following command from a shell
-       or system prompt (while in the installation directory):
+   It is not necessary to modify this path, but you may wish to change it if:
 
-           chmod o+w uploads
+   - Your site runs multiple Drupal installations from a single codebase (modify
+     the file system path of each installation to a different directory so that
+     uploads do not overlap between installations).
 
-     * Access the file system path settings in Drupal by selecting these
-       menu items from the Navigation menu:
+   - Your site runs on a number of web servers behind a load balancer or reverse
+     proxy (modify the file system path on each server to point to a shared file
+     repository).
 
-           Administer > Site configuration > File system
+   - You want to restrict access to uploaded files.
 
-       Enter the path to the new location (e.g.: uploads) at the File
-       System Path prompt.
+   To modify the file system path:
+
+   a. Ensure that the new location for the path exists and is writable by the
+      web server. For example, to create a new directory named uploads and grant
+      write permissions, use the following commands on a Unix/Linux command
+      line:
+
+        mkdir uploads
+        chmod a+w uploads
+
+   b. Navigate to Administration > Configuration > Media > File system, and
+      enter the desired path. Note that if you want to use private file storage,
+      you need to first enter the path for private files and save the
+      configuration, and then change the "Default download method" setting and
+      save again.
 
    Changing the file system path after files have been uploaded may cause
    unexpected problems on an existing site. If you modify the file system path
    on an existing site, remember to copy all files from the original location
    to the new location.
 
+8. Revoke documentation file permissions (optional).
+
    Some administrators suggest making the documentation files, especially
    CHANGELOG.txt, non-readable so that the exact version of Drupal you are
    running is slightly more difficult to determine. If you wish to implement
-   this optional security measure, use the following command from a shell or
-   system prompt (while in the installation directory):
+   this optional security measure, from a Unix/Linux command line you can use
+   the following command:
 
-          chmod a-r CHANGELOG.txt
+     chmod a-r CHANGELOG.txt
 
-   Note that the example only affects CHANGELOG.txt. To completely hide
-   all documentation files from public view, repeat this command for each of
-   the Drupal documentation files in the installation directory, substituting the
+   Note that the example only affects CHANGELOG.txt. To completely hide all
+   documentation files from public view, repeat this command for each of the
+   Drupal documentation files in the installation directory, substituting the
    name of each file for CHANGELOG.txt in the example.
 
-   For more information on setting file permissions, see "Modifying Linux, Unix,
-   and Mac file permissions" (http://drupal.org/node/202483) or "Modifying
-   Windows file permissions" (http://drupal.org/node/202491) in the online
-   handbook.
-
-7. CRON MAINTENANCE TASKS
+   For more information on setting file permissions, see "Modifying Linux,
+   Unix, and Mac file permissions" (http://drupal.org/node/202483) or
+   "Modifying Windows file permissions" (http://drupal.org/node/202491) in the
+   online handbook.
 
-   Many Drupal modules have periodic tasks that must be triggered by a cron
-   maintenance task, including search module (to build and update the index
-   used for keyword searching), aggregator module (to retrieve feeds from other
-   sites), and system module (to perform routine maintenance and pruning on
-   system tables).
+9. Set up independent "cron" maintenance jobs.
 
-   For most sites, the built-in, automated cron feature should be sufficient.
-   Note, however, that cron tasks will only be executed when there are site
-   visitors. You can enable the built-in cron feature at:
+   Many Drupal modules have tasks that must be run periodically, including the
+   Search module (building and updating the index used for keyword searching),
+   the Aggregator module (retrieving feeds from other sites), and the System
+   module (performing routine maintenance and pruning of database tables). These
+   tasks are known as "cron maintenance tasks", named after the Unix/Linux
+   "cron" utility.
 
-          Administer > Configuration > System > Site information
+   When you install Drupal, its built-in cron feature is enabled, which
+   automatically runs the cron tasks periodically, triggered by people visiting
+   pages of your site. You can configure the built-in cron feature by navigating
+   to Administration > Configuration > System > Cron.
 
-   Advanced users may want to ensure that cron tasks are executed periodically.
-   To do this, visit the page "cron.php", which executes maintenance tasks on
-   behalf of installed modules. The URL of the cron.php page requires a "cron
-   key" to protect against unauthorized access.
-   Each cron key is automatically generated during installation and is specific
-   to your site. The full URL of the page, with cron key, is available in the
-   "Cron maintenance tasks" section of the "Status report page" at:
+   It is also possible to run the cron tasks independent of site visits; this is
+   recommended for most sites. To do this, you will need to set up an automated
+   process to visit the page cron.php on your site, which executes the cron
+   tasks.
 
-          Administer > Reports > Status report
+   The URL of the cron.php page requires a "cron key" to protect against
+   unauthorized access. Your site's cron key is automatically generated during
+   installation and is specific to your site. The full URL of the page, with the
+   cron key, is available in the "Cron maintenance tasks" section of the Status
+   report page at Administration > Reports > Status report.
 
-   Most systems support using a crontab utility for automatically executing
-   tasks like visiting the cron.php page. The following example crontab line
-   uses wget to automatically visit the cron.php page each hour, on the hour:
+   As an example for how to set up this automated process, you can use the
+   crontab utility on Unix/Linux systems. The following crontab line uses the
+   wget command to visit the cron.php page, and runs each hour, on the hour:
 
-   0   *   *   *   *   wget -O - -q -t 1 http://www.example.com/cron.php?cron_key=RANDOMTEXT
+   0 * * * * wget -O - -q -t 1 http://example.com/cron.php?cron_key=YOURKEY
 
-   Replace the text "http://www.example.com/cron.php?cron_key=RANDOMTEXT" in the
+   Replace the text "http://example.com/cron.php?cron_key=YOURKEY" in the
    example with the full URL displayed under "Cron maintenance tasks" on the
    "Status report" page.
 
-   More information about cron maintenance tasks are available in the help pages
-   and in Drupal's online handbook at http://drupal.org/cron. Example cron scripts
-   can be found in the scripts/ directory. (Note that these scripts must be
-   customized similar to the above example, to add your site-specific cron key
-   and domain name.)
+   More information about cron maintenance tasks is available at
+   http://drupal.org/cron, and sample cron shell scripts can be found in the
+   scripts/ directory. (Note that these scripts must be customized like the
+   above example, to add your site-specific cron key and domain name.)
 
 
 BUILDING AND CUSTOMIZING YOUR SITE
 ----------------------------------
 
-A new installation of Drupal defaults to a very basic configuration with only a
-few active modules and minimal user access rights. When extending your site,
-you use "modules" and "themes". A module is a plugin that adds functionallity to
-Drupal, while a theme changes the front-end look and behavior of your site.
+A new installation of Drupal defaults to a very basic configuration. To extend
+your site, you use "modules" and "themes". A module is a plugin that adds
+functionality to Drupal, while a theme changes the look of your site. The core
+of Drupal provides several optional modules and themes, and you can download
+more at http://drupal.org/project/modules and http://drupal.org/project/themes
 
-It is important to install these correctly and not mix them in with the core
-Drupal module and theme set (directories modules and themes at the top level).
-So normally you place them under the following paths:
+Do not mix downloaded or custom modules and themes with Drupal's core modules
+and themes. Drupal's modules and themes are located in the top-level modules and
+themes directories, while the modules and themes you add to Drupal are normally
+placed in the sites/all/modules and sites/all/themes directories. If you run a
+multisite installation, you can also place modules and themes in the
+site-specific directories -- see the Multisite Configuration section, below.
 
-Modules:
-  sites/all/modules/example_module
-
-Themes:
-  sites/all/themes/example_theme
-
-If you run a multisite installation you will want to do this a bit differently.
-You can read more about that on the multisite part of this file.
-
-Contributed modules can be found at:
-http://drupal.org/project/Modules
-
-Contributed themes can be found at:
-http://drupal.org/project/Themes
-
-Later on you might want to write your own code, but remember to NEVER modify the
-core modules and themes in Drupal directories modules and themes. Instead use
-the hooks available in the Drupal API. You can read more about the Drupal API
-and how to develop modules at
-http://drupal.org/developing/modules
+Never edit Drupal's core modules and themes; instead, use the hooks available in
+the Drupal API. To modify the behavior of Drupal, develope a module as described
+at http://drupal.org/developing/modules. To modify the look of Drupal, create a
+subtheme as described at http://drupal.org/node/225125, or a completely new
+theme as described at http://drupal.org/documentation/theme
 
 
 MULTISITE CONFIGURATION
@@ -328,12 +328,13 @@ A single Drupal installation can host several Drupal-powered sites, each with
 its own individual configuration.
 
 Additional site configurations are created in subdirectories within the 'sites'
-directory. Each subdirectory must have a 'settings.php' file which specifies the
-configuration settings. The easiest way to create additional sites is to copy
-the 'default' directory and modify the 'settings.php' file as appropriate. The
-new directory name is constructed from the site's URL. The configuration for
-www.example.com could be in 'sites/example.com/settings.php' (note that 'www.'
-should be omitted if users can access your site at http://example.com/).
+directory. Each subdirectory must have a 'settings.php' file, which specifies
+the configuration settings. The easiest way to create additional sites is to
+copy the 'default' directory and modify the 'settings.php' file as
+appropriate. The new directory name is constructed from the site's URL. The
+configuration for www.example.com could be in 'sites/example.com/settings.php'
+(note that 'www.' should be omitted if users can access your site at
+http://example.com/).
 
 Sites do not have to have a different domain. You can also use subdomains and
 subdirectories for Drupal sites. For example, example.com, sub.example.com,
@@ -370,30 +371,32 @@ directory within the site configuration directory. For example, if
 sub.example.com has a custom theme and a custom module that should not be
 accessible to other sites, the setup would look like this:
 
-  sites/sub.example.com/:
-  settings.php
-  themes/custom_theme
-  modules/custom_module
+  sites/sub.example.com/
+    settings.php
+    themes/custom_theme
+    modules/custom_module
 
 NOTE: for more information about multiple virtual hosts or the configuration
-settings, consult the Drupal handbook at drupal.org.
+settings, consult http://drupal.org/getting-started/6/install/multi-site
+
+For more information on configuring Drupal's file system path in a multisite
+configuration, see step 7 above.
 
-For more information on configuring Drupal's file system path in a multi-site
-configuration, see step 6 above.
 
 MORE INFORMATION
 ----------------
 
-- For additional documentation, see the online Drupal handbook at
-  http://drupal.org/handbook.
+- For additional documentation, see the online Drupal handbook:
+  http://drupal.org/handbook
 
 - For a list of security announcements, see the "Security announcements" page
   at http://drupal.org/security (available as an RSS feed). This page also
   describes how to subscribe to these announcements via e-mail.
 
-- For information about the Drupal security process, or to find out how to report
-  a potential security issue to the Drupal security team, see the "Security team"
-  page at http://drupal.org/security-team.
+- For information about the Drupal security process, or to find out how to
+  report a potential security issue to the Drupal security team, see the
+  "Security team" page at http://drupal.org/security-team
 
-- For information about the wide range of available support options, see the
-  "Support" page at http://drupal.org/support.
+- For information about the wide range of available support options, visit
+  http://drupal.org and click on Community and Support in the top or bottom
+  navigation.