Updated: Comment #N
There are a couple of problems with how we are doing hook_help() implementations currently in Drupal 8 and all previous versions. Here is a typical implementation:
/**
* Implements hook_help().
*/
function book_help($path, $arg) {
switch ($path) {
case 'admin/help#book':
$output = '<h3>' . t('About') . '</h3>';
$output .= '<p>' . t('The Book module is used for creating structured, multi-page content, such as site resource guides, manuals, and wikis. It allows you to create content that has chapters, sections, subsections, or any similarly-tiered structure. For more information, see the <a href="!book">online documentation for the Book module</a>.', array('!book' => 'https://drupal.org/documentation/modules/book')) . '</p>';
$output .= '<h3>' . t('Uses') . '</h3>';
$output .= '<dl>';
$output .= '<dt>' . t('Adding and managing book content') . '</dt>';
$output .= '<dd>' . t('You can assign separate permissions for <em>creating new books</em> as well as <em>creating</em>, <em>editing</em> and <em>deleting</em> book content. Users with the <em>Administer book outlines</em> permission can add <em>any</em> type of content to a book by selecting the appropriate book outline while editing the content. They can also view a list of all books, and edit and rearrange section titles on the <a href="!admin-book">Book administration page</a>.', array('!admin-book' => \Drupal::url('book.admin'))) . '</dd>';
$output .= '<dt>' . t('Book navigation') . '</dt>';
...
Here are some problems with the current hook_help() standard, which this issue may be able to fix, and some additional concerns:
There are several possible ways to solve this problem:
0. Since we want to keep translation text chunks relatively small and without markup, would it be possible to use translation context to help group them? [This is probably independent of how the rest of the issues are solved.]
1. We could make a single "standard help" Twig template, which would output the standard About/Uses markup. Then hook_help() could return a renderable array something like this:
return array(
'#theme' => 'help-standard',
'#about' => t('The about text goes here'),
'#uses' => array(
array(
'#header' => t('Using this module'),
'#text' => t('Description here'),
),
array(
'#header' => t('Doing something else'),
'#text' => array(t('First paragraph'), t('Second paragraph')),
),
);
Presumably if a hook_help() wanted to return something completely different, or add something after the standard About/Uses, they could do something different in their render array.
2. We could put the About/Uses text into some kind of a YML file. Docs writers are already using YML for Tours and it's much easier to deal with than PHP concatenation. Question: If it is a YML config file, what happens when Core has an update and a site already has its help config stored -- would it get updated? And if it is some other type of YML file (not part of the config system), would it be automatically translated and what would that buy us?
3. There's a proposal on #1918856: Put each module's help into a separate Twig file → to make each individual hook_help() implementation have its own Twig template.
4. Some kind of README file with Markdown format.
5. There may be other ideas?
a) Figure out which idea is the best for documentation writers, module developers, and translators.
b) Implement it in a patch.
None.
hook_help() would be changed in some way (yet to be determined).
Postponed: needs info
9.5
Last updated
Changes an existing API or subsystem. Not backportable to earlier major versions, unless absolutely required to fix a critical bug.
Not all content is available!
It's likely this issue predates Contrib.social: some issue and comment data are missing.
I think it could be closed as duplicate of 🌱 Deprecate hook_help() and combine with Topics Active
But it looks more like duplicate of #2698035: Add markdown system for HTML-formatted text →
PS: we have docs gate for core and before we can deprecate help it needs policy issue