Help File Fixup: Path module

No, that statement is not true that I know of, at least in the interface. It is true if you have PathAuto installed, but that is not part of core. Otherwise, looks good.

A couple of comments:
a) "and search engines as Google index your content more effectively" Needs the word "such" in there (search engines such as Google)
b) A Drupal path such as member/xyz should not be referred to as a URL. It should be referred to as a path.
c) can create an alias under the "URL path settings" when
How about changing that to
can create an alias under the "URL path settings" secton when
d) For ease of translating, let's not use "whirligigs" as an example product name?

Also I think it is best to put each LI in its own t() call, and as much as possible to keep the HTML tags out of the translation text (except inline tags like EM).

fixed some punctuation, language, broken/missing link arrays, and formatting. moved bit about pathauto into about.

Minor comment: webchick reviewed another patch I was working on (API doc) and commented that using such high numbers for node IDs was unrealistic. This would apply to user IDs as well. e.g. user/25 and node/49 might be more realistic than such high numbers. I'm not sure about path image/9348098 or whatever that was, do those paths exist?

Also, you can add aliases from the manage aliases page.

And if you're cleaning up these minor changes, you could maybe put "contributed module" for Path Auto to make it clear it's not a core module...

One more minor thing: Near the end:
"The Path module allows you to search and view.." Elsewhere, we have not capitalized names of modules (including higher up on this screen).

I like the text other than these minor things, though!

Sorry, another minor adjustment:
"URL path settings secton"
section is misspelled here

3 patches:

help-file-fixup-path-v6.patch
section instead of secton

help-file-fixup-path-v6-using-t-variables.patch
use t('%alias for the path %path', array('%alias' => 'member/jane-smith', '%path' => 'user/123')) again, just in case it was better. not sure about it

help-file-fixup-path-v6-with-code-tag.patch
I think code tag looks better than em, so I suggest this change

I would NOT suggest using variables for the path examples section. Translators will want to make path aliases into their own language, and make them culturally appropriate. So they might not want jane smith, for instance, as the name, or member as the path prefix.

I'm not sure about using code tags for the paths... could go either way, but let's think about the semantics of "is this code" vs. "is this emphasized", rather than the way these two tags are rendered currently in the Seven theme.

So it looks like we agree on this. The first patch from #6 http://drupal.org/files/issues/help-file-fixup-path-v6.patch is close.

Since we now have capitalization standards, this patch needs a small tweak: the name of the module should be written "the Path module".

With that very minor change, I would mark this RTBC. So here's a patch with that small change.

"The Path module allows you to specify aliases for URLs. With such aliases, your users can read URLs better and search engines can index your content more effectively. You can create multiple aliases for a given page."

Couple of things:

1. OMG WHAT IS AN ALIAS?!?!? You talk about it like it's the best thing since sliced bread but don't tell me what it IS! :) You get into it more below, but a 3-word definition in the first sentence here would be nice.
2. We should avoid the use of trademarked names in our help text, methinks. "such as Google" should be removed.
3. "your users can read URLs better" sounds a bit awkward. It's not that we give them mystical URL-reading powers, it's that the URLs are more legible.. or... something.

Ending my review cos I talked about this to Kenn_VM in IRC and he's going to take a crack at a re-roll.

combined original description with new per discussion with webchick in IRC.

Subscribing.

yet another rewording based on suggestions by deviantintegral and dimitrig01

ignore above patch. not patched properly.

real patch ....

found an inconsistency - fixing.

how's this?

one mo time

it dawned on me after reading the entire patch in #16 that were (meaning me) trying to cram examples into the opening paragraph and those examples are indeed already part of the patch in #16 which make the examples I added, redundant. Therefore, marking as needs work. again...

this one may work

:cries:

this one should pass.

correcting incorrect capitalization

removed an incorrect pluralization

now that I'm sure the patches are passing. Here is another with some more clean up.

one more pass at cleanup before sleep.

One more read though and I note that the link to the path module documentation in the first paragraph that I've carried through from #16 should probably be moved to the end of the path documentation rather than where it is currently located. Specifically after 'Managing aliases' info, I'd think.

Will work on this more before turkey tomorrow.

• "help the indexing of content by search engines." => "help search engines index content."
• "see the online handbook entry for Path module." => "see the online handbook entry for the Path module."
• "added, edited and deleted" => "added, edited, and deleted."
• "With clean URLs enabled the aliases become even more readable." => "Clean URLs will remove ?q= from your URLs if your web server supported it at the time your site was installed."
• I'm not sure about linking to a contributed module core help - do any other modules do that? I was going to suggest linking to a listing of path-realted modules on d.o, but it doesn't look like such a category exists.

#37 moved link to path module to end of module documenation.

From #38

1) done

2) done

3) I'm concerned with #3. Would the description included in path module with reference to Clean URLs be better served on the clean urls screen?

We're saying:
"The enabling of clean URLs will remove ?q= from your URLs if your web server supported it at the time your site was installed."
Which sounds a bit like; if the server didn't support it at time of install, you're screwed.

4) removed but can be readded based on the opinion of others.

cleaned up the clean urls description some in the case that it stays here.

Oner more pass.

corrected a typo and cleaned up the clean urls description to read

When <a href="@cleanurl">clean URLs</a> are enabled the ?q= from the path. Clean URL's are automatically enabled at the time of installation if your web server supports this feature.

erp patching against an outdated path.module

my bad. will correct.

- making VeryMisunderstood patch on 41 apply
- point correctly to pathauto (but not sure too if that reference should be there, it easy to remove than to add)
- point correctly to permissions section
- use URLs instead of URL's, since IIRC I read somewhere that we want to use that way, also because there was a typo that made a syntax error in that sentence

thanks marvil07

I wound up tied up with family eating turkey.

OMG this patch got messy! i cleaned up the code formatting, some funky URL arrays, punctuation/caps, and reapplied the help text docs standards. also addressed many of webchick's concerns, removed the stuff about clean urls, and consulted with @kenn_vm and @davereid on irc on a few other tidbits.

i hope this is closer to something that works for everyone!

I've split the clean URL help into a new issue at #644388: Add a status report entry for the Clean URL setting.

1. I think the first sentence is too long. How about "The Path module allows you to specify an aliases, or more easy to read URL for any existing internal system path. Aliases should not be confused with a URL redirect, which allows you to forward a changed URL to a new URL."
2. I still think we should remove the pathauto reference. But if we keep it, the project page has the name capitalized. I think a new d.o taxonomy term ("path management") which would include projects such as pathauto, path redirect, global redirect, etc would be best.
3. about_us should be about-us to promote not using underscores in URLs, which are often confused with spaces.

Otherwise, looking good!

in reference to #48.

more easy is incorrect grammar, I think. more easy sounds like more better. Easier is the word that should likely be used.

"The Path module allows you to specify an alias that can create URL's that are easier to read. Or something.

ok - all those grammatical issues have been updated.

@deviantintegral - i reviewed #2 re: pathauto again with @webchick, and we're going to keep the pathauto reference in. she says ++ to the taxo term suggestion though, so if you can file a new issue regarding that, that would be awesome. thx!

(thanks for the reviews in IRC @Kenn_vm and @davereid!)

.....RTBC?!

http://drupal.org/handbook/modules/path/ should not have a slash at the end of it. Since it's such a small change, once this passes the bot I'll RTBC it unless anyone else has comments.

I've created an issue for path module categories over at #644784: New term for path-related modules.

"or URL that is easier to read" still sounds funny to me. I went with "or custom URL" instead. I'm not sure that that's "it" but I think it's a little less awkward.

Otherwise, this looks great! Committed to HEAD! :)