Update hook_help for Search module

Going to work on it - DC Praque Sprint

Reworked the URLs to the new standard.

Also, all of the cron-related links in this help should be going to admin/config/system/cron and not to wherever they are currently going to.

Reviewed rewritten URLs, changed 2 additional ones, and changed the references to drupal.org/cron per comment #4.

Thanks, looking better! Next time you make a patch, an interdiff would be helpful. :)

There are still a couple of problems with this patch:

a) In About, there is no use of @search in the text, so we don't need that URL.

b) URLs should use !name not @name in t(). See http://drupal.org/node/632280

patch:

- addresses point #6
- changes reference to online docs

I changed component to get feedback from maintainers about changes in Search module between D7 & D8. There seem to be almost no difference (for the users / site builders)

I'm one of the maintainers of search.module. :)

We need to postpone this, as there is another issue
#2042807: Convert search plugins to use a ConfigEntity and a PluginBag
which is actually making some significant changes to the UI for search.module settings.

That other issue went in, so we can probably go back to this issue now.

There's another UI change coming so we should postpone this again:
#2123073: Move index.cron_limit setting to NodeSearch

I don't think we should postpone this on #2123073: Move index.cron_limit setting to NodeSearch any more. However, #1366020: Overhaul SearchQuery; make search redirects use GET query params for keywords and #2156661: Search admin menu entry uses "settings" -- UI-text standards violation are both changing the UI a bit. They are both RTBC. Once those are done, we can return here.

And as a note, when we fix up this help, we should link to the Cron settings page rather than the Status report page when we talk about cron in the help.

This can be worked on now.

Here is a patch. I've tested it out and I think the formatting is good, the text is accurate for the current D8, and the links definitely all work. Thoughts?

#2183113: Update hook_help signature to use route_name instead of path went in, so this patch will need an update.

Assigning to me.

Rerolled. Still needs review.

@jhodgdon - Based on https://api.drupal.org/comment/25348#comment-25348 and other core modules, I have just changed @variable to !variable as a standard convention.

Please see if it makes sense.

Thanks for making that change!

The text in this help still needs review. Since I wrote it, I cannot review it.

A bit of feedback...

+++ b/core/modules/search/search.module
@@ -71,26 +71,25 @@ function search_help($route_name, Request $request) {
+      $output .= '<dd>' . t('The Search module includes a default <em>Search</em> block, which can be enabled and configured on the <a href="!blocks">Block layout page</a>, if you have the Block module enabled. The block is available to users with the <em>Search content</em> permission, and it performs a search using the configured default search page.', array('!blocks' => (\Drupal::moduleHandler()->moduleExists('block')) ? \Drupal::url('block.admin_display') : '#')) . '</dd>';

The default block has the title "Search" but if you want to add a new instance of the block, it's named "Search form" in the "Forms" category. I don't know how to word that.

The permission needed to search is now named "Use search".

Except those two things, everything looks good.

Good catch, and thanks for the careful review! Here's a new patch with different wording on the block, and permission name fixed.

Awesome, thanks @jhodgdon! I've manually tested again (since you added a link) and everything's cool. RTBC'd!

Reading through the help text. Drupalcon Austin.

General question: Should we link to the permissions page when we reference permissions in the help text?

For example:

"Users with Use search permission can..."

becomes

"Users with Use search permission can..."

We could even link straight to that permission using the div id as an anchor but the header menu overlays it.

Anyway, figuring out permissions is a significant part of the learning curve and a link would help.

Thoughts?

Sure, good idea. We have done that in other hook_help docs.

Thanks Ben for your feedback.

There were also some other instances like Use search permission, View published content permission, Use advanced search permission, View user profiles permission and Administer users permission which have been linked to permission page.

All the links work.

As far as I can tell, the interdiff only shows that permission names were turned into links, so RTBC again!

realityloop and I are the process of completely rewriting the text. Here's what I have so far. I'd love your comments. The following is pasted from Evernote so please excuse any formatting problems. Also, the links are missing so just focus on the text, please.

About the Search Module

The Search module provides indexing and keyword search functionality across site content and user profiles.
* Site content is indexed by exact keywords.
* User profiles are indexed by username or e-mail.

The Search module provides two search interfaces for users:
* a search block with basic search functions and
* a search page that has advanced search functions for properly authorized users.

Search module permissions
The following configurable user permissions are provided by the Search module:

* Use search - use the search block or Search page.
* Use advanced search - use the Advanced search options on the Search page.
* Administer search - configure Search module settings

Additional permissions that may affect search results are:

* View published content - search site content using exact keywords.
* View user profiles - search for users by keyword in the user name, and users with the
* Administer users - search for users by email address.

Configuring the Search module
The search module gives administrators that ability to fine-tune how search works.

Configurable search settings include:
* Number of items to index per cron run,
* Indexing settings (word length),
* Active search plugins, and
* Content ranking.

Indexing content
The search module maintains an index of words it finds in your content and content fields. Modules with search integration provide related text that gets indexed with your content, for example, comments and taxonomy terms.

A correctly configured cron maintenance task builds and maintains the content index.

Actions on your site that create or change content causes it to be marked for indexing or reindexing when cron runs. Actions that mark content for reindexing include:

* creating, editing, or deleting content,
* creating, editing, or deleting related text (like comments),
* deleting or editing taxonomy terms,
* enabling or disabling modules that add text to content (such as Taxonomy, Comment, and field-providing modules),
* modifying the fields of your content types,
* changing display parameters of your content types, and
* clicking the "Re-index site" button on the Search settings page.

New or changed content will not be reflected in search results until the next time cron runs. If you have a lot of content on your site, it may take several cron runs for the index to be fully updated.

Search block
The Search module includes a Search form block that can be enabled and configured on the Blocks administration page.

Extending the Search module
By default, the Search module only supports exact keyword matching in content searches.
You can modify this behavior by installing a language-specific stemming module (such as Porter Stemmer for American English), to allow words such as walk, walking, and walked to be matched in the Search module.

Another approach is to use a third-party search technology with stemming or partial word matching features built in, such as Apache Solr or Sphinx. These and other search-related contributed modules can be downloaded by visiting Drupal.org.

For more information, see the online handbook entry for Search module.

This new help text is not accurate in at least one place: User search does not use the Search module's index at all, and mentioning the index in conjunction with User search will be confusing.

The proposed text also has a lot of problems with spelling, grammar, etc...

And we don't really need to tell users things like:
- All of the specific settings they'll be able to configure on the settings page.
- How to use user interfaces.

So... I think we should probably stick with the previous patch and fix it up rather than starting over? I'm not sure what this new text is trying to accomplish that the previous patches didn't? Until we have specific criticism of the previous patch, I'm inclined to say the previous patch is still RTBC. Thanks!

Looks like this patch needs a reroll for some reason... It's probably the email/e-mail patch actually.

Rerolled.

Patch in #31 is empty.

Trying again.

Thanks for the reroll, which looks good this time!

updated as Drupal.org should also be a link.

In general if you make a new patch, you need to set the status back to "needs review" so people can review your patch, rather than leaving it at "reviewed and tested by the community", since your patch had not yet been reviewed.

So... Looking at the interdiff... In contrast to the stated reason for your new patch, you actually made several updates to the text. One is OK, but:

a) ... the previous content remains in the index until next cron runs ... This is not good English. Please change it back to what it was, or put the "next" after "runs".

b) I also disagree with the stated reason for the update: These and other <a href="!contrib-search">search-related contributed modules</a> can be downloaded by visiting Drupal.org. I do not think that drupal.org should really be a link here, since we've already made a link to the *relevant* page where you can search for search-related modules. Why is making drupal.org into a link a good idea, exactly? Why would we want people to go there at all?

I think in this case I would be in favor of keeping the patch in #33 instead of trying to make the revisions suggested by #35.

sorry for not updting the project status.
I have updated the patch with changes stated in #36.
Please review now.

Looks fine now, thanks!

Yoink! :)

Committed and pushed to 8.x. Thanks!