Improve Path Admin Description

How's this read?

"Drupal provides complete control over URLs through aliasing, which is often used to make URLs more readable or easy to remember. For example, if the alias 'about' was assigned to 'node/1', instead of navigating to {$base_url}/node/1, you could navigate to {$base_url}/about"

So two unwritten rules, is try not to mention Drupal and we dont use node in the interface anymore.

I'd say, this paragraph should be like ... So URL aliasing, example...

So not explaining what URL aliasing means, but just giving an example.

"An alias will make a URL available under another name. For example 'node/1' could be named 'about'. A URL can have multiple aliases."

Rationale:
- I wanted to avoid the word "page".
- I wanted to avoid the word "path". The example only shows the path instead of the URL, but I think it is clearer this way.

Why not slightly more direct language, avoiding "will".

+      return '<p>' . t("An alias will make a URL available under another name. For example 'node/1' could be named 'about'. A URL can have multiple aliases.") . '</p>';

to

+      return '<p>' . t("Use an alias to make a path available under a different name (for example, the alias 'about' for the path 'node/1'). A path may have multiple aliases.") . '</p>';

I like Keith's suggestion slightly better. Quick reroll?

I will do one. A slight change is adding a / to identify that it is a url thing

Use an alias to make a path available under a different name (for example, the alias '/about' for the path 'node/1'). A path may have multiple aliases.

If we use "/about", shouldn't we use "/node/1"? And, how does the ui act if someone actually enters the leading /? Someone certainly will do so if we show it like this.

It kills you, but thats a different patch going in soonish I hope.

Yes on "/" :P

Node will probably be optional in Drupal 7, so if possible we should avoid using it for examples.

My shot: An alias makes one path available under another one i.e. user/john for user/1.

The thing with URL is that the small portion of it we're talking about isn't really a URL.

ugh, lets not do it to difficult. Node beign optional here is like 00000.000001%, just do something different for that thing.

Elsewhere in Drupal, I think we refer to this as the "URL path".

I think it is OK to use 'node' in the example -- as Bohjan said, that is pretty minor.

I think the example.com is to much.

An alias makes one URL path available under other ones i.e. http://example.com/user/john for http://example.com/user/1.

I'd strip the single quotes and use EM or possibly CODE tags instead. I am unsure if we should display the domain name differently. If we do, we should avoid class names that describe styling rather than meaning. A class unimportant would in this case be better, since the domain name actually isn't important.

#8 mentioned that a user might enter a leading slash if we are not careful.

#13 and #14 shows the slash is not part of the alias (http://example.con/node/1

#17 has the slash in the wrong part

So if we go with using example.com or some host name and a class, the slash should be in the unimportant part. See #19.

#16 says it's ok to use node.

If we use the phrase URL path (see #16) maybe we don't need any of that anyway.

+      return '<p>' . t("Use an alias to make a URL path available under a different name (for example, the alias 'about' for the URL path 'node/1'). A URL path may have multiple aliases.") . '</p>';

Why not use site site's real URL instead of "example.com"?

#20 is almost there. The terms are abstract enough to warrant an example. My rewrite tries to be yet another bit shorter and simpler:

An alias defines a different name for an existing URL path (for example, the alias 'about' for the URL path 'node/1'). A URL path may have multiple aliases."

Let's avoid the color-coding in help text, please.

Committed to CVS HEAD. Much better than what we have today, but feel free to re-open if we want to discuss this more. Thanks all!