Document Layout Builder functionality in its hook_help() text

Duplicate of #2919811: Write Layout Builder handbook documentation, but this issue summary is better, so closing that one and migrating the tags over.

Yep, stable blocker for sure. Thanks @tim.plunkett and @ifrik. Not sure how I missed this as a stub page should have been an alpha blocker. :) But we definitely should finish it up for 8.7 so that we can make LB stable!

https://www.drupal.org/docs/8/core/modules/layout_builder is the page that's currently linked in hook_help(), but it doesn't exist.

On second thought, reopened #2919811: Write Layout Builder handbook documentation to be specifically about the d.o handbook

I have started the guide: https://www.drupal.org/docs/8/core/modules/experimental-layout-builder

Quick patch for correcting the link to the stub doc pages:

https://www.drupal.org/docs/8/core/modules/experimental-layout-builder

I fixed the handbook page URL instead, it now matches the correct URL in core:
https://www.drupal.org/docs/8/core/modules/layout-builder

See attached.

Compared this to the hook_help() contents of several other modules and this has a similar level of detail. Everything spotted is just nits and some potentially subjective.

1. +++ b/core/modules/layout_builder/layout_builder.module
   @@ -47,8 +47,15 @@ function layout_builder_help($route_name, RouteMatchInterface $route_match) {
   +      $output .= '<p>' . t('Layout Builder allows you to apply <a href=":layout">Layouts</a> to content, custom blocks, and other <a href=":field_help" title="Field module help, with background on content entities">content entities</a>, to customize how they are displayed.', [':layout' => 'https://www.drupal.org/docs/8/api/layout-api', ':field_help' => Url::fromRoute('help.page', ['name' => 'field'])->toString()]) . '</p>';
   

   This is a run-on sentence. Starting a new one after "content entities" should work.

2. +++ b/core/modules/layout_builder/layout_builder.module
   @@ -47,8 +47,15 @@ function layout_builder_help($route_name, RouteMatchInterface $route_match) {
   +      $output .= '<dd>' . t('Layout Builder is enabled on the "Manage Display" section of the <a href=":field_ui">Field UI</a>. This allows you to control the output of each type of display individually. For example, a "Basic page" might have view modes such as Full and Teaser, with each view mode having different layouts selected.', [':field_ui' => Url::fromRoute('help.page', ['name' => 'field_ui'])->toString()]) . '</dd>';
   

   Here "Manage Display" is referred to as a section, in the linked Field UI docs, it's referred to as a page.

   Unsure if this is excessive for hook_help - is it possible to explain that Layout Builder can be enabled/disabled on a per-view-mode basis, and the layouts can be unique for each? This is a soft suggestion because I attempted to come up with a good way to word this and couldn't produce anything concise/clear.

3. +++ b/core/modules/layout_builder/layout_builder.module
   @@ -47,8 +47,15 @@ function layout_builder_help($route_name, RouteMatchInterface $route_match) {
   +      $output .= '<dd>' . t('If enabled, this allows each individual content item to have a custom layout. Once the layout for an individual content item is overridden, changes to the Default layout will no longer take effect. Overridden layouts may be reverted to return to matching and being synchronized to their Default layout.') . '</dd>';
   

   Possible rephrasing to slightly shorten the first sentence and clarify the subject-verb relationship of the second.
   "If enabled, each individual content item can have a custom layout. Once the layout for an individual content item is overridden, changes to the Default layout will no longer effect it..."

#14
1)
Switched from

Layout Builder allows you to apply Layouts to content, custom blocks, and other content entities, to customize how they are displayed.

to

Layout Builder allows you to use Layouts to customize how content, custom blocks, and other content entities are displayed.

2)
Improved this (I think?)

3)
Made this change, but had to switch from effect to affect :D

Those changes work for me - lets send it up the chain.

Thanks a lot! This looks close. Found one problem, and pondered on one thing that looked fine at the end:

1. +++ b/core/modules/layout_builder/layout_builder.module
   @@ -47,8 +47,15 @@ function layout_builder_help($route_name, RouteMatchInterface $route_match) {
   +      $output .= '<p>' . t('Layout Builder allows you to use <a href=":layout">Layouts</a> to customize how content, custom blocks, and other <a href=":field_help" title="Field module help, with background on content entities">content entities</a> are displayed.', [':layout' => 'https://www.drupal.org/docs/8/api/layout-api', ':field_help' => Url::fromRoute('help.page', ['name' => 'field'])->toString()]) . '</p>';
   

   I believe linking to the layout API documentation right away as the first link to explain what we are dealing with is not appropriate for site builder docs. I looked if there is a better place to look for layouts explained, but the "For more information ..." link already explains that.

   I would just remove the link from Layouts here.

2. +++ b/core/modules/layout_builder/layout_builder.module
   @@ -47,8 +47,15 @@ function layout_builder_help($route_name, RouteMatchInterface $route_match) {
   +      $output .= '<dd>' . t('Layout Builder can be selectively enabled on the "Manage Display" page in the <a href=":field_ui">Field UI</a>. This allows you to control the output of each type of display individually. For example, a "Basic page" might have view modes such as Full and Teaser, with each view mode having different layouts selected.', [':field_ui' => Url::fromRoute('help.page', ['name' => 'field_ui'])->toString()]) . '</dd>';
   

   The reference to field UI sounded too technical as well, but after reading the actual field_ui_help(), it seems like that explains it fine and it makes sense to link it like this, so this looks fine after all.

#17

1) Fair enough, removed.

2) Great! Also I should note I borrowed this from content_moderation_help().

Re-RTBCing since the only change was to remove a link.

Thanks all! :)