Add renderable / localizable text element - make modules help text readable and flexible - pluggable localization

Great idea but not sure about text() function. maybe better to rethink a hook_help() to return $build array
Also we have #markup and #item elements that could be extended to support translation

Edit: patch has a lot of Tab characters

I was asked to comment on this in regards to the help system. Although we had thougts of completely getting rid of the current hook_help() system for Drupal 8, at this point I can confidently say that it's not going to happen for Drupal 8 (not going into the reasons why, but it isn't).

That said, I don't understand from this issue why the text() function is better than t(), but if you think it is, I have no objection to changing hook_help() to use it.

Just to clarify... From the perspective of someone writing hook_help() text, changing from t() to text() doesn't appear to change anything I would need to do, except that I have to think of a unique text name to use as the first argument to text(). The other two arguments, unless I am mistaken, are the same as t().

So can you clarify what the purpose of this change would be? Who is it helping (translators maybe?), and how?

+++ b/core/includes/common.incundefined
@@ -2390,6 +2390,29 @@ function l($text, $path, array $options = array()) {
+ * Build a structured text element to be rendered later.

It would be good to document the #localize, #localize_function and #replace feature.
If there is a text() function it should better explain when it's used instead of just plain t().

+++ b/core/modules/help/help.admin.incundefined
@@ -51,10 +51,14 @@ function help_page($name) {
+      	'#items' => $links,
+      	'#title' => t('@module administration pages', array('@module' => $info[$name]['name']))

Here and below in the hook_help implementations are tabs instead of spaces.

One related issue here: #1484002: Add support for named texts for the locale system. Introducing drupal_text()

rerolled the patch. There was a problem when creating the interdiff.

Um.... How is this text going to be translatable? I mean, how is it going to get into the localize.drupal.org databaes?

And I don't really think this is any more readable than the current way of doing things anyway? How is making a text element more readable than calling t()? The other changes in this patch (reformatting) could be done in t() anyway?

See also #5.

8.1 meterial

Oh, I forgot about this issue!

So I actually have a working system for Configurable Help topics that creates plugins for text segments, in a sandbox project. I should adapt that patch for Core here. See https://www.drupal.org/sandbox/jhodgdon/2369943

Using that system, a hook_help() implementation like this:

      $output .= '<h3>' . t('About') . '</h3>';
      $output .= '<p>' . t('The Help module generates <a href=":help-page">Help reference pages</a> to guide you through the use and configuration of modules, and provides a Help block with page-level help. The reference pages are a starting point for <a href=":handbook">Drupal.org online documentation</a> pages that contain more extensive and up-to-date information, are annotated with user-contributed comments, and serve as the definitive reference point for all Drupal documentation. For more information, see the <a href=":help">online documentation for the Help module</a>.', array(':help' => 'https://www.drupal.org/documentation/modules/help/', ':handbook' => 'https://www.drupal.org/documentation', ':help-page' => \Drupal::url('help.main'))) . '</p>';
      $output .= '<h3>' . t('Uses') . '</h3>';
      $output .= '<dl>';
      $output .= '<dt>' . t('Providing a help reference') . '</dt>';
      $output .= '<dd>' . t('The Help module displays explanations for using each module listed on the main <a href=":help">Help reference page</a>.', array(':help' => \Drupal::url('help.main'))) . '</dd>';
      $output .= '<dt>' . t('Providing page-specific help') . '</dt>';
      $output .= '<dd>' . t('Page-specific help text provided by modules is displayed in the Help block. This block can be placed and configured on the <a href=":blocks">Block layout page</a>.', array(':blocks' => (\Drupal::moduleHandler()->moduleExists('block')) ? \Drupal::url('block.admin_display') : '#')) . '</dd>';
      $output .= '</dl>';

would become a render array, something like this:

$sections = [];
$sections[] = ['#type' => 'header', '#text' => t('About')];
$sections[] = ['#type' => 'paragraph', '#text' => t('The Help module generates <a href=":help-page">Help reference pages</a> to guide you through the use and configuration of modules, and provides a Help block with page-level help. The reference pages are a starting point for <a href=":handbook">Drupal.org online documentation</a> pages that contain more extensive and up-to-date information, are annotated with user-contributed comments, and serve as the definitive reference point for all Drupal documentation. For more information, see the <a href=":help">online documentation for the Help module</a>.', array(':help' => 'https://www.drupal.org/documentation/modules/help/', ':handbook' => 'https://www.drupal.org/documentation', ':help-page' => \Drupal::url('help.main')))];
$sections[] = ['#type' => 'header', '#text' => t('Uses')];
$sections[] = ['#type' => 'description_name', '#text' => t('Providing a help reference')];
$sections[] = ['#type' => 'description_value', t('The Help module displays explanations for using each module listed on the main <a href=":help">Help reference page</a>.', array(':help' => \Drupal::url('help.main')))];
$sections[] = ['#type' => 'description_name', '#text' => t('Providing page-specific help')];
$sections[] = ['#type' => 'description_value', t('Page-specific help text provided by modules is displayed in the Help block. This block can be placed and configured on the <a href=":blocks">Block layout page</a>.', array(':blocks' => (\Drupal::moduleHandler()->moduleExists('block')) ? \Drupal::url('block.admin_display') : '#'))];

$build = [
  '#type' => 'text_sections',
  '#sections' => $sections,
];

Then the 'text_sections' render element and the various text section plugins take care of making this into H3, paragraph, and DL/DT/DD elements.

It doesn't take care of the localization part -- we already have t() for that -- but it does take care of abstracting away some of the embedded HTML stuff.

Thoughts? If this seems like an improvement, I can make that part of the sandbox module into a patch here.

As a note... One of the problems identified in the current issue summary here is not really a problem any more: t() is now not translating until later. Instead, it makes a "translatable markup" object and it is only translated if the translation is actually being rendered.

I think that the patch proposed earlier on this issue is not in line with how we are currently doing things in Core either... The translation system has been overhauled with these TranslatableMarkup objects, and rather than introducing a function like text() in common.inc, we'd want to use the render system more directly.

Also, the proposal in the issue summary, where the HTML tags would be added back into the translated strings and the strings would become very long, is not viable given localize.drupal.org. See meta issue #2592487: [meta] Help system overhaul for more details... adding this as its child also.

Adding related issue, which also had a patch, but which was abandoned recently.

I think that rather than make another patch(or re-roll) needs to define a good and concerted solutions

With the current way to write help for a module

Agree:
- It isn't have a localizeable text element for use at another part of code.
- It isn't readable and flexible .
- It isn't pluggable.

Current proposal solution:
- Chunk the current $output variable at $output associative array when you can divide in parts your help and this can be standardized too.
In concept It is too according with @jhodgdon proposal solution but in other way.

So to recover the discussion
Another proposal solution:
I think that this is an use that I really will like when I writing a help of module:

$build = [
 'title' => '....',
 'about' => '...',
 'uses' => '...'
 'references' => [
    'website' => some link
    'repository' =>some link
    'documentation' =>some link
 ]
]

Where we will write only the main thinks on documentations with references to hard documentations that almost all contribute modules have in other places.