[META] Convert hook_help() module overview text to topics

Converting this into a recipe for making child issues.

Adding novice tag to this and to the child issues.

I just went through the whole process for the core Action module. I think it is fine, except that it's not really ready to go until we get the initial core patch in:
#2920309: Add experimental module for Help Topics
Which should be soon, so I have not bothered to mark this issue as Postponed, but I did add a note to the issue summary.

Updating issue summary for working on this before the initial experimental module patch is committed.

Please don't assign yourself this entire meta issue! Updating issue summary here to clarify. Also I need to make a small edit on the template issue.

Also as a note, I think it is best to only create issues you are ready to work on right now. As we go, we may want to edit the issue template (as I just did). Thanks!

Tagging for DrupalCon

Updating issue summary with tag suggestion.

Updating issue summary with suggestion that when editing to add an issue, you also put a short note in the comments. :)

Thanks for getting started on this @vadim.hirbu!!

Since the parent issue's patch has not yet been committed, here is a Twig file that can be used as a sample (from the actions module child issue patch). Updating issue summary to point to this file. I will also add a note to the child issue template.

Adding note about file name of the sample Twig template.

Thanks again for leading the mentored group today! Your steps look perfect!

Although I have to say the last time I tried simplytest.me as you suggested, it didn't come up. Hopefully that has been fixed for the mentoring day... I imagine it will get some heavy use. Anyway you might want to test it with those patchs and make sure it does work today, if you didn't already.

To answer your questions:
- For these patches, let's just put each module's new Twig file(s) in core/modules/that_module/help_topics. We have another issue to write more topics and organize them, so that will work fine -- we can decide then if topics belong elsewhere.
- Adding blank lines in the Twig is fine with me, probably a good idea.
- Wrapping the text lines at 80 characters may be problematic. The text has to be extracted with POTX and get onto localize.drupal.org. I don't think it should have line feeds in it in random places. So, let's not wrap them. You might look at other existing Twig files in Core with %trans text in them and see if they have line feeds, and then check on localize to see if those line feeds look weird... or better yet just don't put in line feeds to be safe.

I have to go out for an early morning appointment, but should be back by 9 AM Seattle time, so I'll be online on Slack and DrupalChat for the contribution day today, if you have any more questions. Thanks again!!

Yeah, the PO and POT formats have that funky multi-line thing going on. But what I'm talking about is what gets stored in the Drupal and/or localize.d.o database if there are newlines in the middle of the trans/endtrans text.

So, I looked at the POTX code that Drupal and localize.d.o use to extract strings from Twig, which is at
https://git.drupalcode.org/project/potx/blob/7.x-3.x/potx.inc#L1766

There are various places in there and a function it calls that save strings, but they pretty much all look like one of these two calls:

$save_callback(_potx_format_quoted_string('"' . trim($string) . '"'), $context, $file, $line);
$save_callback(_potx_format_quoted_string('"' . trim(implode('', $text)) . '"'), $context, $file, $line);

Notice the trim() there -- initial/final whitespace will be removed (including newlines). The call to _potx_format_quoted_string just escapes quotes.

The second example line there says that if $text is an array, it's imploded. That array is being generated by successive Twig parsing tokens... but I'm not really sure whether a newline corresponds to a different token, or whether a string with newlines in it will all be one token, thus not be imploded. The Twig parsing code is not exactly easy to read.
https://github.com/fabpot/Twig/blob/master/lib/Twig/Lexer.php [not sure if that is the version being used either]

Anyway, it is definitely OK to have a newline after the opening {% trans } tag, and one before the endtrans tag too.

But that one Core example you have from core/modules/node/templates/node-add-list.html.twig suggests that long lines should not be broken up in Twig files.

Adding another task to the Remaining Tasks section of the issue summary about making sure that the list of modules is current before marking this as Fixed.

A question has come up about permissions links. Making a child issue to discuss/decide what to do.
#3047781: Decide what to do about permissions links in help topics

We need to postpone this until the #2920309: Add experimental module for Help Topics gets committed. No idea when/if that might happen right now...

I will now unblock the child issues too. And actually removing the notes about the parent issue from the summary.

Fixing link to create new issues in the issue summary so they start out Active now not Postponed.

That sounds like a good idea.

The current tests for the module overviews from hook_help test for certain content, like the appearance of the module name. But I don't think we can/should test for content in help topics, because they're not supposed to be module-oriented. I also don't think we should require each module to have at least one topic file, because there may be circumstances where a particular module's files are put elsewhere (like a group of modules that share topics or putting them in the core space), or where a particular module doesn't need help because its tasks are described elsewhere.

So... for templates that do exist, I think we could write a test. Here's the sample template file (linked in the issue summary): https://www.drupal.org/files/issues/2019-04-08/sample.html_.twig_.txt

Here are some things I think we could maybe test for:
- meta tag for the title (label) must be present (help_topic:label)
- allowed meta tags: help_topic:label, help_topic:top_level, help_topic:related -- there must not be any others [although maybe someone would write a subclass of the plugin manager that would use other meta tags?]
- there must not be an H1 tag
- if there is an h3 tag, there must be an h2 tag; if there is an h4, there must be an h3; etc. (proper hierarchy of headings)
- can we test for HTML syntax validation, once it's rendered from Twig?
- is it possible to test whether all of the text in the file is actually wrapped in translation commands {% trans }?

Actually, shouldn't we move this discussion of tests to #3037228: Add more test coverage to Help Topics? I'll do that...

Yesterday I asked in Slack about whether we should have one issue per module (as we currently have here), or put the issues into larger chunks. The answer was that it would be better to group certain modules together. For example, all the migrate modules should probably be in one patch, so that the migrate system maintainer can review them together, and because the topics might refer to multiple modules.

So... looking through the list of modules, as well as MAINTAINERS.txt, here are some proposed groups. Any thoughts? If we like these groups, I will adjust the issue summary and/or combine issues that we already have:

• block, block_content, block_place
• editor, ckeditor
• theme-related: color, breakpoint, layout_builder, layout_discovery, field_layout
• media-related: file, image, media, media_library, responsive_image
• config, config_environment
• internationalization: config_translation, content_translation, language, locale
• content_moderation, workflows, workspaces
• field-related: datetime, datetime_range, entity_reference, field, field_ui, link, options, telephone, text
• system: action, automated_cron, ban, dblog, syslog, system, update, user
• speed: big_pipe, dynamic_page_cache, page_cache
• admin UI: contextual, tour, help [help_topics already done], quickedit, settings_tray, shortcut, toolbar, inline_form_errors
• node, comment, filter, path, taxonomy
• menu_link_content, menu_ui
• migrate, migrate_drupal, migrate_drupal_multilingual, migrate_drupal_ui
• hal, jsonapi, rdf, rest, serialization, basic_auth
• statistics, history, tracker
• views, views_ui

Modules to leave as "loners":
aggregator, book, forum, contact, search, simpletest

Thoughts?

We should start some review notes for these issues... starting with the syntax checks mentioned in #53 until we have a test written. I'll put those, and what andypost and I just discussed in Slack, into the issue summary.

As a note, we will need to reorganize the topics on #2687107: Reorganize topics into sensible outline, and/or write more topics -- for now I think it is OK to just make most of them top-level. Adding this to the review notes.

I do not think we want to have a top-level topic called "Core Modules". We don't want any module overview topics. We want task-oriented topics instead. These issues about "convert hook_help" really mean "rewrite useful content from hook_help into task-oriented help". The issue summary template for the child issues explains this.

The groups in #55 seem to be OK (after Slack discussion). So, reorganizing the list in the issue summary, and I'll combine the existing issues too.

I'm going to do these in 2 batches. Here's the first set.

More issue combining. List is done now.

We really need to come up with better standards for what we want in help topics than what we have in the issue template on
#3041928: ISSUE TEMPLATE -- Do not edit -- template for making child issues

All it really says right now is:

We want to end up with one or more topics about the tasks that you can do with this module. So, read the help and figure out a good way to logically divide it up into tasks. Each task will need to be in its own topic.
...
Do not just copy the text of the old module overview word-for-word. We don't want an overview of the module -- we want one or more topics that are task-centered, that would be useful for someone managing or building a Drupal site. If you need to explain a concept, put that in a separate section or sections within the related task topic, with headers like "What is/are...?" question, such as "What are actions?".
...
And in the Review section:
Also verify that it is task-based help, and that concepts that need to be explained are in separate sections with "What is/are" questions as headers (such as "What is an action?").

This is not enough... or at least it doesn't seem to be. People are just copy/pasting the hook_help and thinking that is good enough, or are reviewing without actually looking critically at whether it's good help.

We probably need standards for the topic titles too, which if they are task based, I suggest we do like the User Guide and have them be "Verbing a noun" titles?

Regarding the last comment, we made some changes to the template issue today and I'm copying them to all the child issues.

We are now maintaining the review tips on #3041928: ISSUE TEMPLATE -- Do not edit -- template for making child issues (and if they change, copying them to the child issues), so removing that section from here. I verified the information there is pretty much duplicated on the child issues.

I added a new issue to make sure the help topics that were committed in the initial commit of Help Topics adhere to the new standards (they don't currently).
#3072312: Review/fix/delete existing help topics

Fixing issue link for the Contact module issue.

I asked in Slack and found out from @xjm that all of the code *and topics* related to the Help Topics module need to stay under core/modules/help_topics until we are Stable. I have updated all the existing child issues as well as the template issue, to reflect that policy.

Updating summary to remove outdated link to sample file. Point to standards instead.

Removing entity_reference and block_place modules from the list (will also go to their issues and remove), as they are both "hidden" modules in Drupal Core as of now.

Just a note that I went through the list of modules currently in core/modules for 8.9.x and all of them are in the issue list in the issue summary, as of today.

It looks like there are possibly plans to rename or deprecate several modules for Drupal 9. See this related issue.

Adding a little follow-up issue for Block topics.

Splitting off actions and views bulk operations into their own issue.

Created issues for the few remaining module groups. Also checked over the list of modules and verified it contains all the current, non-hidden modules.

Moving filter module from #3067727: Convert comment, node, path, taxonomy module hook_help() to topic(s) to #3067614: Convert filter, ckeditor, editor module hook_help() to topic(s) (see comments on either issue about this change).

I don't think we want to be creating help topics for experimental modules (too much in flux, and may not get added to core for real), so adding a note to the issue summary.

Simpletest module is gone in 9.0 so removing that issue.

@benjifisher found a typo in one of the topics, so I created a child issue to collect minor cleanup fixes in committed patches:
#3121340: Fix up minor copy problems in help topics

We don't need the instructions for creating child issues any more.

Commenting to update the summary colors.

I inadvertently moved Contact out of the Done category with my last change. Moving back to done.

And Big Pipe too!

The Appearance group of modules has also been committed. Thanks alexpott!

menu done

Migrate is done #3073476: Convert migrate, migrate_drupal, migrate_drupal_multilingual, migrate_drupal_ui module hook_help() to topic(s)

This should not really be a Novice issue.

Another one done!

Config is done!

Internationalization modules are done!

Content moderation is done!

Moving above issue to top of summary and adding a few other clean-up things.

One more done, woot! Thanks @larowlan.

And another one... getting close here!

one cleanup done!