sites/all/README.txt clarification [#101455]

When experimenting with various installs of 5.0-beta2 I even read some of the documentation. One piece that confused me was sites/all/README.txt

// $Id: README.txt,v 1.1 2006/11/11 22:53:59 drumm Exp $

This directory should be used to place downloaded and custom modules and
themes which are common to all sites. This will allow you to more easily
update Drupal core files.

When I put a custom module in this directory it wasn't found by Drupal v5 and couldn't be configured. I subsequently found that when I used a subdirectory for the downloaded modules called "modules" Drupal V5 was able to find them. I presume a similar directory naming is required for themes also.

Now so long as I've understood this correctly I suggest the README.txt wording is changed:

// $Id: README.txt, ...

This directory should be used to place downloaded and custom modules and
themes which are common to all sites. This will allow you to more easily
update Drupal core files.

All downloaded custom modules should be placed in a subdirectory called 
modules and all custom themes should be placed in a subdirectory called 
themes as follows:
   settings/all/modules
   settings/all/themes

Comment	File	Size	Author
#8	readme_subdir_explain.patch	617 bytes	vjordan
#8

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Comment #1

vjordan CreditAttribution: vjordan commented 5 December 2006 at 13:29

Category:

feature

» bug

Actually, I think this is a bug report of sorts, rather than a feature request.

Comment #2

greggles

he/him

English

Denver, Colorado, USA

CreditAttribution: greggles commented 5 December 2006 at 15:37

Status:

Needs review

» Active

This seems like a good improvement.

I'm changing the status as this is not a patch - see http://drupal.org/diffandpatch for instructions on creating patches.

For relatively trivial changes like docs I think it can be useful to decide on the text prior to creating the patch. My preference would be for the language to read:


These installation-wide modules and themes should be placed in 
subdirectories called modules and themes as follows:
   settings/all/modules
   settings/all/themes

Comment #3

vjordan CreditAttribution: vjordan commented 6 December 2006 at 14:32

Priority:

Minor

» Normal

Greg, Thanks for the guidance on using the patching system - first toe in the water for me.

+1 for your wording which is clear, concise and complete.

Following the revision process and the related href="http://drupal.org/node/45111"> priority levels of issues I suggest the following:

change to priority 'normal' in that somebody following the README won't get the modules to work.
wait for a couple of days to see if there's any further feedback before creating the patch.

Does this sound about right?

Apologies for cluttering this bug but it's kind of related: would it be good practice to create issues for http://drupal.org/node/22283 (best practices for file/directory management) and http://drupal.org/node/53705 ("using the /sites directory") given that sites/all now comes into play? If so, how would one go about this?

Comment #4

pwolanin CreditAttribution: pwolanin commented 6 December 2006 at 21:21

I made quick updates to: http://drupal.org/node/22283, and http://drupal.org/node/53705

post your feedback here rather than opening new issues.

Comment #5

greggles

he/him

English

Denver, Colorado, USA

CreditAttribution: greggles commented 6 December 2006 at 21:39

Thanks, pwolanin.

@vjordan - if you are interested in revising the documents in the handbook please join the http://lists.drupal.org/listinfo/documentation documentation list and hang out for a little while providing feedback on ideas. Then you can ask for permission to edit the handbook (the hanging around and providing input makes you more likely to be approved quickly, you can ask sooner if you feel that's justified).

Comment #6

oadaeh CreditAttribution: oadaeh commented 7 December 2006 at 05:47

As long as you're trying to correct the text, can you please make sure it says:

sites/all/modules
sites/all/themes

instead of:

settings/all/modules
settings/all/themes

Comment #7

vjordan CreditAttribution: vjordan commented 7 December 2006 at 10:58

oadaeh: thanks for correcting the error in directory naming. It would have really confused the likes of me.

pwolanin - some suggestions on your quick updates...
http://drupal.org/node/53705
I seem to understand better when information is presented in small or really small chunks. This is a style thing rather than a principle so I can live with what you have. How would the following read (but note the two typo corrections anyway)?

New for Drupal 5.x: With Drupal 5.x, you have another, simpler option. You can put your non-core modules and themes, and your files directory in the sites/all directory. Modules and themes in this directory will be available to all sites in a multi-site installation. This arrangement can simplify[typo corrected] the transition to and from a development host and a production host, and make it easier to replicate installations.

The sites/all directory will already exist when you download Drupal. Add modules, themes, and files sub-directories to sites/all. For a single site installation leave settings.php in the sites/default directory. You'll have a directory structure that looks like this:
/drupal
...
Once you've done all this, the 'back end' of your site will be cleanly organized. The main Drupal directory will contain only the standard 'core' files, and all of your custom themes, add ons, settings, and so on will be tucked away in /sites/all [directory typo fixed]

Backing up the /sites directory [I think this is what you meant], and your Drupal database, will give you everything you need to restore the site in the event of a crash, or move it to a new server. In addition, you're giving yourself room to grow: if you ever want to run additional web sites (maintain a separate 'testing' version of your site on the same server) it's as easy as creating a new directory in /sites.

http://drupal.org/node/53705
Maybe just change "For a normal (single site) installation..." to "For a single site installation..."

Comment #8

vjordan CreditAttribution: vjordan commented 11 December 2006 at 10:25

Status:

Active

» Needs review

File	Size
readme_subdir_explain.patch	617 bytes

The patch based on the above is attached. Not sure I have all the patch headers correct.

Comment #9

pwolanin CreditAttribution: pwolanin commented 12 December 2006 at 00:31

Title:	sites/all/README.txt clarification suggested	» sites/all/README.txt clarification
Project:	Documentation	» Drupal core
Version:		» 5.x-dev
Component:	Documentation in CVS	» base system