[documentation] [Documentation bug] Incorrect /sites/all documentation
karldied
drupal-docs at drupal.org
Thu Jan 18 13:11:55 UTC 2007
Issue status update for
http://drupal.org/node/103915
Post a follow up:
http://drupal.org/project/comments/add/103915
Project: Documentation
Version: <none>
Component: Installation
Category: bug reports
Priority: normal
Assigned to: karldied
Reported by: Crell
Updated by: karldied
Status: fixed
Thanks for QA on my update, and opening new issue /node/110446 on an
additional clarification needed.
I also meant to mention when updating this issue to 'closed' that
104340 - Drupal multi-site setup documentation: request for comments [1]
remains open and is still dealing with the whole multi-site installation
matter (vhosts, etc), and there is also a comment on where /files is
best placed. In this case, the new issue is probably best separate.
[1] http://drupal.org//node/104340
karldied
Previous comments:
------------------------------------------------------------------------
Mon, 18 Dec 2006 03:35:09 +0000 : Crell
The example of the "new 5.0" sites/all support on this page [2] is
wrong. It says:
/drupal
/sites
/default
settings.php
/all
/modules
/themes
/files
Which is not correct. sites/all does NOT provide any magic support for
files, and in fact putting files there is a rather bad idea. It's for
modules and themes that you want shared only. A more correct example
would be:
/drupal
/sites
/default
/files
/modules
/themes
settings.php
/all
/modules
/themes
(I'm not sure what the rule is for what counts as "critical" for
documentation, but I figure "incorrect information" is a good guess.
Please correct if I'm mistaken.)
[2] http://drupal.org/node/53705
------------------------------------------------------------------------
Mon, 18 Dec 2006 03:42:44 +0000 : Crell
It's not just the example, I just realized, but the descriptive text as
well.
------------------------------------------------------------------------
Mon, 18 Dec 2006 12:52:00 +0000 : pwolanin
@Crell - the site works either way if you're doing a single site
installation. So, there is no real difference unless the user is
transitioning from single site to multi-site. In that case, the user
would have been best advised to put everything in /sites/sitename all
along (as per the initial example).
So, the real question is simply what do we want to define as the "best"
practice.
------------------------------------------------------------------------
Mon, 18 Dec 2006 16:07:53 +0000 : Crell
Best practice is to keep site-specific files with site-specific code,
not to confuse it with site-generic code. Yes it will not-break if you
put your files directory in sites/all/files, but it technically doesn't
break if you put it in themes/engines/files either. That doesn't make
it a good idea. :-) Encouraging people to keep site-specific everything
together from the get-go is a good thing.
------------------------------------------------------------------------
Tue, 19 Dec 2006 13:42:07 +0000 : vjordan
A question is whether the guidance for sites/all/modules and
sites/all/themes is also appropriate guidance for sites/all/files? I'd
say probably not in most cases. Can a situation be envisaged where this
is a sensible configuration? Probably. Best practice and good guidance
might need to focus on the main cases, at least initially.
This page is a bit confusing to a new user - I was one fairly recently.
A lot of information comes down in pretty hefty chunks. I'd suggest a
bit of structure on this page would make it more useful. A suggested
structure is presented below. I'm suggesting a complete explanation for
each of v4 and v5 (although much is the same), and a short explanation
of the differences so people who know v4 can jump straight to the bit
they need.
- start page -
[h1]v4.6, 4.7
1. What goes into /sites (settings, contrib & custom modules, contrib &
custom themes, files)
2. When to use multiple settings files (include explanation that each
site still needs to be configured using admin->modules and
admin->themes)
3. Directory structure
- Include cross-reference to the Connecting Drupal part of
install.txt [3] for specific guidance on how to name the
subdirectories.
4. Using the /sites directory to simplify backups
[h1]Enhancements for v5
- Role of /sites/all in multi-site configurations.
- Use of sites/all/themes, sites/all/modules.
- Guidance on placing /files (in appropriate site subdir).
[h1]v5.x
1. What goes into /sites (settings, contrib & custom modules, contrib &
custom themes, files)
2. When to use multiple settings files
3. Directory structure
- Include cross-reference to the Connecting Drupal part of
install.txt [4] for specific guidance on how to name the
subdirectories.
- Role of /sites/all in multi-site configurations.
- Use of sites/all/themes, sites/all/modules.
- Guidance on placing /files (in appropriate site subdir).
4. Using the /sites directory to simplify backups
[h1] Related links
Pointer to how to set up multi-sites http://drupal.org/node/43816
- end page -
I'm suggesting h1 for the main headings and an appropriate name in h2
where I show numbers above.
I'm not sure about the 'related links' bit. I just know the multi-site
issue is really hard to get your head around, /sites is one piece of it.
The comments below the handbook page illustrate that difficulty.
If you think it would help to structure the page along these lines I'd
be happy to make a draft for review.
[3] http://drupal.org/node/260
[4] http://drupal.org/node/260
------------------------------------------------------------------------
Tue, 19 Dec 2006 14:38:27 +0000 : vjordan
I just read the style guide [5] so forget what I said about h1, h2 in
the post above. At the moment I don't know how to offer better structure
and stay compliant with the style guide. Breaking this into child nodes
might work but I'll need to think about this quite differently.
[5] http://drupal.org/node/24221
------------------------------------------------------------------------
Tue, 16 Jan 2007 05:32:13 +0000 : karldied
This posting addresses /sites directory for initial single-site set-up;
please QA the new documentation [6]. The multi-site setup still needs
work. This post is so long because the topic is a tangle:
*Issues: *
This issue: Incorrect /sites/all documentation [7].
Doc issue: node/53705 - /sites directory use [8].
Doc issue: Drupal multi-site setup documentation: request for comments
[9]
Project issue: Change default for files directory [10]
Project issue: Use of sites/default/files as the default files
directory [11]
*Handbook pages: *
Use the /sites directory to keep Drupal tidy [12] (did one small fix
and moved from under 'best practices' to under 'Multi-site installation
and set-up')
File and directory management [13] (under 'best practices')
Installing Drupal [14] (first chapter of 'Installation and
configuration' book)
Multi-site installation and set-up [15] (a grouping page with minimal
content and one comment)
Database table prefix (and sharing tables across instances) [16] (under
Basic site configuration)
/sites directory setup [17] (under Installing Drupal, just written)
One of the key problems with 'Use the /sites directory to keep Drupal
tidy' is that it tries to cover both single site and multi-site setup.
As stated in an earlier comment, it is also overly wordy and not well
organized.
I wrote /sites directory setup [18] to establish the basic, single-site
setup, using best practices, and mentioning that other specific
configuration would also work. The fact that some common files are kept
in /sites/all while others are kept in /sites/default is explained. (I
still think it would be better to have these two locations for common
files combined! It creates confusion because it is not obvious which
common items go where, and there is no strong reason for their
separation.)
/sites directory setup [19] recommends (based on what the above topics
seem to say) for an initial single-site set-up of:
/sites/all/modules
/sites/all/themes
/sites/default/settings.php
/sites/www.example.com/files
Crell and pwolanin, you probably understand this a lot better than me,
but from review the above, you wouldn't want /modules and /themes under
both /sites/default and /sites/all though it would probably work.
1. QA /node/276, /sites directory setup
2. Re-title /node/53705 from 'Use the /sites directory to keep Drupal
tidy' to '/sites directory use in multi-site installations'
3. Focus /node/53705 on multi-site set-up (as doc issue Drupal
multi-site setup documentation: request for comments [20] seems to have
decided).
I removed the error from /node/53705 of placing /files under /all, and
referenced '/sites directory setup' for initial configuration.
However, I'm sure it could still use more work.
vjordan: the <strong> or <b> tag can be used in place of the h1 tags
you suggested, with paragraphs or ol under each.
-karldied
[6] http://drupal.org/node/276
[7] http://drupal.org/node/103915
[8] http://drupal.org/node/109169
[9] http://drupal.org/node/104340
[10] http://drupal.org/node/23467
[11] http://drupal.org/node/98824
[12] http://drupal.org/node/53705
[13] http://drupal.org/node/22283
[14] http://drupal.org/node/260
[15] http://drupal.org/node/43816
[16] http://drupal.org/node/2622
[17] http://drupal.org/node/276
[18] http://drupal.org/node/276
[19] http://drupal.org/node/276
[20] http://drupal.org/node/104340
------------------------------------------------------------------------
Tue, 16 Jan 2007 06:51:13 +0000 : Crell
That's a lot of pages that I don't have time to review all together at
the moment. :-) Regarding sites/all vs. sites/default, however, they
should not at all be merged. D5 finally split them up.
The primary use of sites/all is to replace the use of the top-level
modules directory. In multi-site until now, there was no way to have a
module or theme shared between sites other than putting it in the
top-level directory along with core modules. That's a maintenance
problem, because upgrading core means you have to work around other
files you've added. With core modules now having their own directories,
that makes it an even messier issue. With sites/all, there is no excuse
to ever put anything in /modules or /themes.
On a single-instance site, you're right that there's not a huge
difference. What I tend to do myself lately is to use sites/all for 3rd
party modules (Views, CCK, other stuff out of contrib) and sites/default
for modules I wrote myself specifically for a site or 3rd party modules
that I had to modify for some reason. That gives me a nice clean
separation between "my code", which I update myself, and "someone else's
code", which I can, for the most part, just drop new versions of in
without worrying about overwriting my own modifications. That may not
be something most users need (if they're not writing their own modules,
then it doesn't make a difference), but it's the usage pattern that I've
settled on.
------------------------------------------------------------------------
Tue, 16 Jan 2007 07:31:48 +0000 : karldied
Crell wrote: "What I tend to do myself lately is to use sites/all for
3rd party modules (Views, CCK, other stuff out of contrib) and
sites/default for modules I wrote myself specifically for a site or 3rd
party modules that I had to modify for some reason."
OK, so if I understand this correctly: I can put contrib modules in
/sites/all/modules or in /sites/default/modules, to the same affect:
available to all sites in a multi-site setup? Same for themes? (Of
course, I recognize that site-specific items can also go in
/sites/www.example.com...)
Then, since /files goes in /sites/www.example.com or /sites/default,
what real reason is there to use /sites/all? What goes in there that
can't be put in /sites/default? (Except that it provides a convenient
division for the two types of non-core modules you work with?)
------------------------------------------------------------------------
Tue, 16 Jan 2007 07:53:12 +0000 : Boris Mann
"
OK, so if I understand this correctly: I can put contrib modules in
/sites/all/modules or in /sites/default/modules, to the same affect:
available to all sites in a multi-site setup? Same for themes? (Of
course, I recognize that site-specific items can also go in
/sites/www.example.com...)
"
No. Only items placed in sites/all/modules (themes, etc.) will be
available to all sites.
Also, we're confusing best practices with what works. I applaud more
best practices work...but there isn't consensus. My personal
recommendation:
* keep ONLY modules that you really are going to use on all sites in
sites/all/modules
* don't use default at all (i.e. all installs are "multi site") ---
symlink default/ to your "main" site
* for each site (even if only one site...), do
sites/example.com/modules, /files, /tmp, /themes
So, having said that....you can see how "multi site" is really the
default nature of Drupal.
------------------------------------------------------------------------
Tue, 16 Jan 2007 09:07:31 +0000 : karldied
Ahh... /sites/default/modules only works for Crell because there is no
/sites/example.com directory? In any case, the documentation (for
initial setup) stands correctly. I'll add idea of using the symlink, and
having a /tmp in each /sites/example.com Thanks.
------------------------------------------------------------------------
Tue, 16 Jan 2007 14:58:12 +0000 : Crell
The setup I described would work equally well for multi-site, just with
a lot of shared modules. (Whether it's better to share as much or as
little as possible between multi-sites is a subjective question I won't
address right now.) I was describing a single-site usage for sites/all.
If you're running a full multi-site, then what Boris describes makes
sense.
The logic for how sites/default vs. sites/example.com works hasn't
changed since 4.6, AFAIK. sites/all is, functionally, the same as the
top-level /modules and /themes directories. There's really not much
more going on in the way of magic.
------------------------------------------------------------------------
Thu, 18 Jan 2007 01:27:40 +0000 : karldied
Primarily, I removed the original error reported in this issue report:
the discussion of /modules and /themes in /sites/default. I also made
the language more straight forward where I made updates.
The 4.6 and 4.7 section was mostly duplicative, so I moved one best
practice up to the main section, and condensed this section down to the
difference from 5.x.
@vjordan: I believe also addressed all your comments. Its new placement
under "Multi-site installations" 43816 a couple days ago took care of a
link back to the multi-site install page.
------------------------------------------------------------------------
Thu, 18 Jan 2007 09:40:56 +0000 : vjordan
@karldied:- good job promptly dealing with a variety of issues in this
area. I was slowly making my way through the pages you referenced above
and I noted a number of possible problem areas. Today I see most of
those have been dealt with. Closing this thread is a good move, but I'm
cross-referencing here an issue at http://drupal.org/node/110446 related
to this set of updates.
More information about the documentation
mailing list