[documentation] [Documentation bug] sites/all/README.txt clarification suggested
vjordan
drupal-docs at drupal.org
Mon Dec 11 10:25:46 UTC 2006
Issue status update for
http://drupal.org/node/101455
Post a follow up:
http://drupal.org/project/comments/add/101455
Project: Documentation
Version: <none>
Component: Documentation in CVS
Category: bug reports
Priority: normal
Assigned to: Anonymous
Reported by: vjordan
Updated by: vjordan
-Status: active
+Status: patch (code needs review)
Attachment: http://drupal.org/files/issues/readme_subdir_explain.patch (617 bytes)
The patch based on the above is attached. Not sure I have all the patch
headers correct.
vjordan
Previous comments:
------------------------------------------------------------------------
Tue, 05 Dec 2006 13:28:19 +0000 : vjordan
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
------------------------------------------------------------------------
Tue, 05 Dec 2006 13:29:15 +0000 : vjordan
Actually, I think this is a bug report of sorts, rather than a feature
request.
------------------------------------------------------------------------
Tue, 05 Dec 2006 15:37:02 +0000 : greggles
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
------------------------------------------------------------------------
Wed, 06 Dec 2006 14:32:19 +0000 : vjordan
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 [1] 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?
[1] http://drupal.org/node/10261
------------------------------------------------------------------------
Wed, 06 Dec 2006 21:21:13 +0000 : pwolanin
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.
------------------------------------------------------------------------
Wed, 06 Dec 2006 21:39:57 +0000 : greggles
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).
------------------------------------------------------------------------
Thu, 07 Dec 2006 05:47:10 +0000 : oadaeh
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
------------------------------------------------------------------------
Thu, 07 Dec 2006 10:58:59 +0000 : vjordan
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..."
More information about the documentation
mailing list