You are here

Adjust documentation for aliased multi sites to include more info and examples.

As requested by redndahead, I suggest to make a slight documentation change in the aliased multi site instructions by including a custom port example. Please refer to my patch at: http://drupal.org/node/231298#comment-3910010.

I understand that you want things to line up, but since we don't do that in Drupal, we shouldn't do that in our examples either.

b)

+ * When index.php is called, Drupal tries to discover an appropriate+ * configuration directory based on the website's hostname, port, and pathname.+ * This file allows you to define a set of aliases that map hostnames, ports and

We don't "call" index.php. Someone visits a page on the site. And Drupal doesn't "try" to discover an appropriate config file, it chooses one. Then in the next line, it says "this file", but there is no file referred to (the previous sentence refers to a directory). So this paragraph needs a rewrite.

c)

+ * //'The url to alias' => 'A directory within the sites directory',

Should be a space after the // for readability, and "url" should be "URL". And see comment (a) here too. Hmmm... Actually the array key is not actually the URL to alias, because one example is "localhost.example", and this is for localhost/example. And none of these are URLs anyway -- URLs are things like http://whatever.com. So you need to find a better way to describe these if you are going to put a comment into the array.

d)

+ * the same as the domain of the live server. Since Drupal stores file paths+ * into the database (files, system table, etc.) this will ensure the paths

---> stores file paths in the database [need to fix this in two places in the patch]

e) Do not repeat documentation. There are 3 spots in this patch with the same documentation. It would be much better to use a line like "See abc() for details" rather than having to maintain the same documentation in 3 places.

a) ok
b) ok
c) Original intent was to improve the readers ability to determine which was the URL and which was the directory. Since there really isn't a name for this type of formatting, I just added '(formatted like examples)' to show that it's not a normal URL.
d)k
e)I trimmed down the core functions and made those comments more appropriately explain what the function does and point to the default.settings.php, and examples.sites.php. There's still some repetition of (c), but that's to provide a quick reference down towards the $sites declaration similar to how settings.default.php has a $databases example, then another example near the $databases declaration.

+++ b/sites/example.sites.php...+ * This file allows you to define a set of aliases that map hostnames, ports and

Needs comma before "and".

b)

+ * Aliases are defined in an associative array named $sites. To create a+ * directory alias for http://www.drupal.org:8080/mysite/test whose+ * configuration file is in sites/example.com the array should look like:

That in-code comment makes no sense at all to me, and actually I don't think we should put in-code comments inside @code tags at all. Put the explanation in the text instead.

d)

+ * The URL, http://www.drupal.org:8080/mysite/test/, could be a symbolic link or+ * an Apache Alias directive that points to the Drupal root containing+ * index.php. An alias could also be created for a subdomain. See the online+ * Drupal installation guide for more information on setting up domains,+ * subdomains, and subdirectories.+ *+ * @see default.settings.php+ * @see conf_path()+ * @see http://drupal.org/documentation/install/multi-site */

How about turning the text "online Drupal installation guide" into a link using @link?

Needs a space before (formatted like examples).... but what does that actually mean -- what examples? It's not really a URL at all (especially if it has a port)... I think this just needs to be reworded somehow (not sure how).

We're pretty close! #18-a wasn't done, and I think the whole thing could use a little copy editing. There are several places that are still a bit awkward in how they are worded. I also think some of this would benefit from using our standard documentation list syntax.http://drupal.org/node/1354#lists

attached is a patch fixing the issue in 18a that also existed in bootstrap.inc. Rewording documentation isn't my strongest suit, so I'm going to unassign this patch so someone else can take a look at it.

+ * configuration file found will be used and any others will be ignored. If no

This line has two spaces between any and others.

c) still in default.settings.php:

+ * http://www.drupal.org:8080/mysite/test/, the 'settings.php' is searched in+ * the following directories:...+ * Notice that if you are installing on a non-standard port number, prefix the

- is searched -> file is searched for
- Notice -> Note

d) In reading the documentation for find_conf_path():

/** * Finds the appropriate configuration directory for a given host and path. *+ * Finds a matching configuration directory by stripping the website's hostname+ * from left to right and pathname from right to left. The first configuration+ * file found will be used and the remaining ones will be ignored. If no+ * configuration file is found, returns a default value '$confdir/default'. See+ * default.settings.php for examples on how the URL is converted to a directory.

I just looked at the code for this function, and this is actually not quite accurate. There is an undocumented parameter $require_settings (this needs an @param to be added to the documentation). If that parameter is TRUE (default), then a directory has to have a settings.php file in it to be considered to be a match. If it is FALSE, then the directory just has to exist to be considered a match. This paragraph should explain this (or reference the $require_settings parameter documentation). This paragraph just refers to "configuration file" being found, which is not accurate (and also doesn't explicitly say it is looking for a file named settings.php).

e) I think we should join these two paragraphs in default.settings.php (start the second sentence with "However"):

* The configuration file to be loaded is based upon the rules below. *+ * If the multisite aliasing file named sites/sites.php is present, it will be+ * loaded, and the aliases in the array $sites will override the default+ * directory rules below. See sites/example.sites.php for more information about+ * aliases.

f) In example.sites.php:

+ * As an example, to create a directory alias for:+ * http://www.drupal.org:8080/mysite/test whose configuration file is in+ * sites/example.com, the array should be written as such:

This second documentation block will not be recognized by the API module (or displayed on api.drupal.org), because it is not documenting a function, global variable, etc. It just needs to be made part of the previous documentation block instead. (When you do this, move the @see lines down to the bottom of the new, larger documentation block.) Actually... I think that all of this can be deleted completely (the information is presented above):

+ * If a file named sites.php is present in the $confdir, it will be loaded+ * prior to scanning for directories.+ *+ * Aliases are defined in an associative array named $sites. The array is+ * written in the format: '<port>.<domain>.<path>' => 'directory'.+ * As an example, to create a directory alias for:+ * http://www.drupal.org:8080/mysite/test whose configuration file is in+ * sites/example.com, the array should be written as such:

I guess I wasn't quite clear, sorry! I think these two paragraphs should be combined... Something like:

If a file named sites.php is present in the $confdir, it will be loaded prior to scanning for directories. That file can define aliases in an associative array named $sites. The array is written [...]

b) Also, this same section of documentation needs the correction from (f) in #30.

c) (c) from #30 needs to be redone. "Notice" became "Not" instead of "Note", and the "file is searched for" replacement for "is searched" wasn't put in.

d) in (g) from #30 I didn't really mean to completely eliminate the second documentation block with the examples... I think we should keep these lines from the previous patch:

I made the change requested in comment #34. I also noticed that there was another similar problem in bootstrap.inc so I updated that as well ("// Export the following settings.php variables to the global namespace" now has a colon at the end). Here you go.

Looks good now, thanks! This might have to wait for a few days to be committed, as there's a large "avoid commit conflicts" issue waiting... also I am currently on a slow internet connection, and traveling for the next week, so if one of the other core committers wants to do it that might be good. :)

Since Jennifer's already been involved in this issue, and since there are A LOT of docs here, I'm going to assign this to her to drive home. But just so you know, this doesn't conflict in any way with any of the "Avoid commit conflicts" patches atm.