Background:
This issue is part of the task to update the hook_help texts of the Drupal 8 modules:
#1908570: [meta] Update or create hook_help() texts for D8 core modules

Tasks:
- review / write the hook_help text according to help guidelines

Comments

Cyberschorsch’s picture

Going to work on it - DC Praque Sprint

Cyberschorsch’s picture

Status:Active» Needs review
StatusFileSize
new8.86 KB
PASSED: [[SimpleTest]]: [MySQL] 58,641 pass(es).
[ View ]

Reworked the URLs to the new standard.

ifrik’s picture

Status:Needs review» Needs work

Thanks @Cyberschorsch for rewriting the links.
Now it needs checking - and where necessary rewritting the text.

jhodgdon’s picture

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.

lmirabile’s picture

Assigned:Unassigned» lmirabile
Issue summary:View changes
Status:Needs work» Needs review
StatusFileSize
new10.2 KB
PASSED: [[SimpleTest]]: [MySQL] 59,374 pass(es).
[ View ]

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

jhodgdon’s picture

Status:Needs review» Needs work

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

batigolix’s picture

Component:documentation» search.module
Assigned:lmirabile» Unassigned
Status:Needs work» Needs review
Parent issue:» #1908570: [meta] Update or create hook_help() texts for D8 core modules
StatusFileSize
new11.09 KB
new11.11 KB
PASSED: [[SimpleTest]]: [MySQL] 59,855 pass(es).
[ View ]

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)

jhodgdon’s picture

Status:Needs review» Postponed

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.

jhodgdon’s picture

Status:Postponed» Needs work

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

jhodgdon’s picture

Status:Needs work» Postponed

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

jhodgdon’s picture

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.

jhodgdon’s picture

Status:Postponed» Active

This can be worked on now.

jhodgdon’s picture

Status:Active» Needs review
StatusFileSize
new11.49 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 69,518 pass(es).
[ View ]

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?

jhodgdon’s picture

Status:Needs review» Needs work
jhodgdon’s picture

Assigned:Unassigned» jhodgdon

Assigning to me.

jhodgdon’s picture

Assigned:jhodgdon» Unassigned
Status:Needs work» Needs review
StatusFileSize
new11.47 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 70,598 pass(es).
[ View ]

Rerolled. Still needs review.

amitgoyal’s picture

StatusFileSize
new12.16 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 71,611 pass(es).
[ View ]

@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.

jhodgdon’s picture

Thanks for making that change!

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

mparker17’s picture

Status:Needs review» Needs work
Issue tags:+Novice

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.

jhodgdon’s picture

Status:Needs work» Needs review
StatusFileSize
new4.23 KB
new12.25 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 71,788 pass(es).
[ View ]

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

mparker17’s picture

Status:Needs review» Reviewed & tested by the community

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

Ben Finklea’s picture

Reading through the help text. Drupalcon Austin.

Ben Finklea’s picture

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?

jhodgdon’s picture

Status:Reviewed & tested by the community» Needs work

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

amitgoyal’s picture

Status:Needs work» Needs review
StatusFileSize
new12.81 KB
FAILED: [[SimpleTest]]: [PHP 5.4 MySQL] Unable to apply patch new-search-help-2091359-25.patch. Unable to apply patch. See the log in the details link for more information.
[ View ]
new6.63 KB

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.

mparker17’s picture

Status:Needs review» Reviewed & tested by the community

All the links work.

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

Ben Finklea’s picture

Status:Reviewed & tested by the community» Needs review

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.

jhodgdon’s picture

Status:Needs review» Reviewed & tested by the community

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!

Status:Reviewed & tested by the community» Needs work

The last submitted patch, 25: new-search-help-2091359-25.patch, failed testing.

jhodgdon’s picture

Issue tags:+Needs reroll

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

lokapujya’s picture

Status:Needs work» Needs review
Issue tags:-Needs reroll
StatusFileSize
new0 bytes
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 72,067 pass(es).
[ View ]

Rerolled.

jhodgdon’s picture

Status:Needs review» Needs work
Issue tags:+Needs reroll

Patch in #31 is empty.

lokapujya’s picture

Status:Needs work» Needs review
Issue tags:-Needs reroll
StatusFileSize
new12.81 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 72,067 pass(es).
[ View ]

Trying again.

jhodgdon’s picture

Status:Needs review» Reviewed & tested by the community

Thanks for the reroll, which looks good this time!

joshi.rohit100’s picture

StatusFileSize
new12.89 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 72,064 pass(es).
[ View ]
new9.88 KB

updated as Drupal.org should also be a link.

jhodgdon’s picture

Status:Reviewed & tested by the community» Needs work

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.

joshi.rohit100’s picture

Status:Needs work» Needs review
StatusFileSize
new12.82 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 72,803 pass(es).
[ View ]
new8.49 KB

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

jhodgdon’s picture

Status:Needs review» Reviewed & tested by the community

Looks fine now, thanks!

webchick’s picture

Status:Reviewed & tested by the community» Fixed

Yoink! :)

Committed and pushed to 8.x. Thanks!

  • webchick committed c865d19 on 8.x
    Issue #2091359 by joshi.rohit100, lokapujya, amitgoyal, jhodgdon,...

Status:Fixed» Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.