Index: INSTALL.txt
===================================================================
RCS file: /cvs/drupal/drupal/INSTALL.txt,v
retrieving revision 1.34
diff -u -r1.34 INSTALL.txt
--- INSTALL.txt	5 Jun 2006 08:53:05 -0000	1.34
+++ INSTALL.txt	27 Jun 2006 04:01:45 -0000
@@ -118,24 +118,38 @@
    will be removed according to the pattern above if no port-specific
    configuration is found, just like a real subdomain.

-   Each site configuration can have its own site-specific modules and
-   themes that will be made available in addition to those installed
-   in the standard 'modules' and 'themes' directories. To use
-   site-specific modules or themes, simply create a 'modules' or
-   'themes' 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:
+   NOTE: for more information about multiple virtual hosts or the
+   configuration settings, consult the Drupal handbook at drupal.org.

+4. INSTALLING MODULES AND THEMES
+
+   Drupal ships with a number of default modules and themes in the
+   'modules' and 'themes' directories, respectively. You can download
+   additional modules and themes from http://drupal.org/project.
+
+   The recommended place to put new modules and themes is in the 'sites'
+   directory. To make a module or theme available to all sites, simply
+   place it under the sites/all/modules directory or sites/all/themes
+   directory. To make it available to only one site, place it in the
+   sites/sub.example.com/modules or sites/sub.example.com/themes directory.
+
+   For example, to make module_a and theme_a available to all sites, but
+   module_b and theme_b available only to sub.example.com, the setup
+   would look like this:
+
+     sites/all/:
+       themes/theme_a
+       modules/module_a
      sites/sub.example.com/:
        settings.php
-       themes/custom_theme
-       modules/custom_module
+       themes/theme_b
+       modules/module_b

    NOTE: for more information about multiple virtual hosts or the
-   configuration settings, consult the Drupal handbook at drupal.org.
+   configuration settings, consult the Drupal handbook at
+   http://drupal.org/handbook.

-4. CONFIGURE DRUPAL
+5. CONFIGURE DRUPAL

    You should consider creating a "files" subdirectory in your Drupal
    installation directory. This subdirectory stores files such as
@@ -161,7 +175,7 @@
    Create an account and login. The first account will automatically
    become the main administrator account with total control.

-5. CRON TASKS
+6. CRON TASKS

    Many Drupal modules (such as the search functionality) have periodic
    tasks that must be triggered by a cron job. To activate these tasks,
Index: modules/system.module
===================================================================
RCS file: /cvs/drupal/drupal/modules/system.module,v
retrieving revision 1.328
diff -u -r1.328 system.module
--- modules/system.module	5 Jun 2006 08:53:05 -0000	1.328
+++ modules/system.module	27 Jun 2006 04:01:49 -0000
@@ -673,13 +673,14 @@
 }

 /**
- * Returns an array of files objects of the given type from both the
- * site-wide directory (i.e. modules/) and site-specific directory
- * (i.e. sites/somesite/modules/). The returned array will be keyed
- * using the key specified (name, basename, filename). Using name or
- * basename will cause site-specific files to shadow files in the
- * default directories. That is, if a file with the same name appears
- * in both location, only the site-specific version will be included.
+ * Returns an array of files objects of the given type from the site-wide
+ * directory (i.e. modules/), the all-sites directory (i.e. sites/all/modules/)
+ * and site-specific directory (i. e. sites/somesite/modules/). The returned
+ * array will be keyed using the key specified (name, basename, filename). Using
+ * name or basename will cause site- specific files to shadow files in the
+ * default directories. That is, if a file with the same name appears in both
+ * the site-wide directory and site-specific directory, only the site-specific
+ * version will be included.
  *
  * @param $mask
  *   The regular expression of the files to find.
@@ -700,6 +701,8 @@
   $searchdir = array($directory);
   $files = array();

+  // Always search sites/all/* as well as the global directories
+  $searchdir[] = 'sites/all';
   if (file_exists("$config/$directory")) {
     $searchdir[] = "$config/$directory";
   }
Index: sites/README.txt
===================================================================
RCS file: sites/README.txt
diff -N sites/README.txt
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ sites/README.txt	1 Jan 1970 00:00:00 -0000
@@ -0,0 +1,31 @@
+// $Id$
+
+WHAT IS THE sites/ DIRECTORY?
+-----------------------------
+
+The sites/ is the recommended place to put:
+
+  - contributed modules from http://drupal.org/project/Modules
+  - miscellaneous directories
+  - custom modules
+  - modified core modules
+
+The benefits are:
+
+  - keep your files tidy
+  - to backup your website, simply backup the sites directory
+
+
+OK, SO WHERE SHOULD I PUT MY THEME/MODULE?
+------------------------------------------
+
+For a quick start, nothing complicated, read:
+
+  - sites/all/modules/README.txt
+  - sites/all/themes/README.txt
+
+For more information about advanced installations, refer to:
+
+  - INSTALL.txt
+  - http://drupal.org/node/258
+
Index: sites/all/modules/README.txt
===================================================================
RCS file: sites/all/modules/README.txt
diff -N sites/all/modules/README.txt
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ sites/all/modules/README.txt	1 Jan 1970 00:00:00 -0000
@@ -0,0 +1,21 @@
+// $Id$
+
+WHAT IS THE sites/all/modules/ DIRECTORY?
+-----------------------------------------
+
+This is the recommended directory for contributed and custom modules.
+For example:
+
+  - sites/all/modules/module_a/
+  - sites/all/modules/module_b/
+
+
+NOTE:
+
+This is not the only location for non-core modules, for more information
+about advanced installations, please read INSTALL.txt.
+
+For step by step instructions on setting up your Drupal website, please
+visit the Installation and Configuration page at drupal.org:
+
+  - http://drupal.org/node/258
Index: sites/all/themes/README.txt
===================================================================
RCS file: sites/all/themes/README.txt
diff -N sites/all/themes/README.txt
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ sites/all/themes/README.txt	1 Jan 1970 00:00:00 -0000
@@ -0,0 +1,21 @@
+// $Id$
+
+WHAT IS THE sites/all/themes/ DIRECTORY?
+-----------------------------------------
+
+This is the recommended directory for contributed and custom themes.
+For example:
+
+  - sites/all/themes/theme_a/
+  - sites/all/themes/theme_b/
+
+
+NOTE:
+
+This is not the only location for non-core themes, for more information
+about advanced installations, please read INSTALL.txt.
+
+For step by step instructions on setting up your Drupal website, please
+visit the Installation and Configuration page at drupal.org:
+
+  - http://drupal.org/node/258