Help module help mentions context-sensitive help and shouldn't

Thanks, what you did looks good! But there is also a mention of the context-sensitive help up a few lines in the "About" section. Can you fix that too please?

Looks good, thanks!

I agree that the hook_help docs should be moved into a system.module *.api.php file. I also agree it should mention how the help is displayed, which it currently doesn't do. Can we do that on a separate issue please though? I filed:
#2263047: hook_help should be moved and should explain how help is displayed
for that piece.

We have a separate issue open to update the system module hook_help(). It is really missing a LOT, not just this piece, and I had already added a comment there that it needs this piece. I would rather not do this as part of this issue here, but we could... that other issue is postponed. See #2091363-12: Update hook_help for System module

Discussed this with webchick in IRC... We should also (for now) update the System module help (add a "Uses" item) to talk about context-sensitive help being displayed in the System Help block. And we should do it in this patch. And then when we've got this into 8, backport to Drupal 7, because we checked and the system behaves the same way there.

I just filed a meta-issue where we need to discuss the top-of-page help:
#2263359: hook_help(): Top of page help sections can't link to help pages without a fatal error or checking for help module

I just edited the issue summary to remove a task. We are not wanting to wait for the other issue to be resolved. For now we need to document what the modules do now, and I think we're going to continue to have top-of-page help anyway.

Also... If someone is actually working on this, please assign the issue to yourself... for the moment have taken out the "working on this now" from the issue summary, since I do not think anyone is working on it.

Looks good... but

+      $output .= '<dt>' . t('Providing context-sensitive help') . '</dt>';
+      $output .= '<dd>' . t('The System module displays context-sensitive advice and explanations on various pages.') . '</dd>';

This isn't very great documentation, because it doesn't mention that this help is displayed in a block. If someone doesn't have this block placed in a region in their admin theme, they won't get the hep displayed. So... We have hook_help pages for various modules that refer to blocks; we should do something similar here to other help that mentions blocks.

Also maybe we should say that this help is provided by other modules, and is generally for administration pages?

No... We are not talking here about contextual links -- that is something different, and is provided by the Contextual Links module. We are talking here about the System Help block.

Ummm.... So: Generally, I like the text in #22 a lot better than the text in #21, and I believe it is more accurate as far as what the System module and other modules are doing... so let's use that as a starting point. ... how about this -- I don't think we need to say any more than this:

---
Providing administrative help

Page-specific administrative help text that is provided by the System module and other modules is displayed in the System help block. This block can be placed and configured on the Block layout page.
---

As a note: When you link to the Block layout page, make sure to check whether the Block module is enabled first. There is an example of how to do this in the Menu module hook_help().

Thanks, that looks good! Can someone please give this a quick manual test (the Help and System module help from admin/help) to make sure both are still formatted OK, and also in the new section in System help, make sure the links work, and that UI text matches the actual Drupal UI?

Thanks! The formatting looks good. So we still need a manual test on the new section in System module to verify the links work, and that the UI text matches what you see in the UI (especially the block name).

Good catch! Patch still needs manual testing as described in #29.

We have a separate issue to update the System help as a whole:
#2091363: Update hook_help for System module

So the patch in #32 is out of scope for this issue. Let's please keep this issue specifically only about moving this one piece of help from the Help module to System module. Thanks!

Please disregard the patch in #32 (you can put it on the other issue), and go back to the patch in #30.

I went back and tested the patch in #30.

It is 99% good! Two things to fix:

a) I do not know what the change is in system.module in the patch above the new section, but can we take that out? This patch should only be adding a new section to that help function. I mean this change should be removed from the patch:

-      $output .= '<dd>' . t('In order for the site and its modules to continue to operate well, a set of routine administrative operations must run on a regular basis. The System module manages this task by making use of a system cron job. You can verify the status of cron tasks by visiting the <a href="@status">Status report page</a>. For more information, see the online handbook entry for <a href="@handbook">configuring cron jobs</a>. You can set up cron job by visiting <a href="@cron">Cron configuration</a> page', array('@status' => url('admin/reports/status'), '@handbook' => 'http://drupal.org/cron', '@cron' => url('admin/config/system/cron'))) . '</dd>';
+      $output .= '<dd>' . t('In order for the site and its modules to continue to operate well, a set of routine administrative operations must run on a regular basis. The System module manages this task by making use of a system cron job. You can verify the status of cron tasks by visiting the <a href="@status">Status report page</a>. For more information, see the online handbook entry for <a href="@handbook">configuring cron jobs</a>. You can set up cron job by visiting <a href="@cron">Cron configuration</a> page.', array('@status' => url('admin/reports/status'), '@handbook' => 'http://drupal.org/cron', '@cron' => url('admin/config/system/cron'))) . '</dd>';

b) As noted in #32, the name of the help block is "System Help", and the capitalization is incorrect in the patch.

Thanks, the latest patch looks good to me too!

Thanks again everyone! Committed to 8.x.