Fix online docs references in Help to conform to our standards [#2493475]

Problem/Motivation

On #2488032: Integrate help test into module uninstall test and #2473105: Update hook_help texts that link to modules that can be uninstalled, we wrote a test to check whether the help pages generated by hook_help() for each of our Core modules conforms (at a basic level anyway) with our help standards, which can be found at https://www.drupal.org/node/632280

The test failed for 23 modules on an assertion that there is a link to the online documentation for the module in the right format. The correct link text, for a module called "Foo Bar", is:

online documentation for the Foo Bar module

The list of modules that failed the test is:
action
ban
basic_auth
block_content
ckeditor
color
content_translation
contextual
dblog
entity_reference
field_ui
filter
forum
hal
language
node
page_cache
search
simpletest
statistics
tour
tracker
update

Proposed resolution

a) Fix all of these modules' hook_help() implementations (these are functions called, for instance, update_help() in the core/modules/update/update.module file) so that they have a link with the right text in it. I looked through a few of these, and the reasons they are failing are usually one of the following:
- They have the word "the" also in the help text, so for instance it might say:
For more information, see <a href="...">the online documentation for the Foo Bar module</a>.. In this case, move the word "the" out of the link to just before the link.
- There is an old-style link like: For more information, see the online handbook for the <a href="...">Foo bar module</a>. In this case, the sentence needs to be updated so it conforms to the current help standards.
- They don't have the link at all. In this case, the sentence needs to be added. See the Help text standards for how to do this: https://www.drupal.org/node/632280
- Possibly some other problems... anyway they should all end up uniformly complying to our standards.

b) Remove the "@todo" in core/modules/system/src/Tests/Module/InstallUninstallTest.php that points to this issue, and un-comment the code line below the @todo line. This will verify that all the help texts have been fixed.

Remaining tasks

a) This issue is postponed on #2488032: Integrate help test into module uninstall test and also on #2473729: Review the hook_help for Internal page cache module.
b) Once both of those have been Fixed, un-postpone this issue and make a patch as described in the Proposed Resolution.

Contributor tasks needed
Task	Novice task?	Contributor instructions	Complete?
Create a patch that makes the tests pass	Yes	Instructions

User interface changes

Help will conform to our standards better.

API changes

None.

Beta phase evaluation

Reference: https://www.drupal.org/core/beta-changes
Issue category	Task because it is updating help to conform to standards
Issue priority	Normal because nothing is non-functional, just not uniform
Unfrozen changes	Unfrozen because it only changes strings/documentation

Comment	File	Size	Author
#19	2493475-18.patch	36.14 KB	ifrik
#19	8.0.x: PHP 5.5 & MySQL 5.5 13,985 pass
#16	2493475-online-docs-15.patch	29.05 KB	ifrik
#16	8.0.x: PHP 5.5 & MySQL 5.5 13,907 pass
#9	2493475-9.patch	38.05 KB	ifrik
#9	8.0.x: PHP 5.5 & MySQL 5.5 13,903 pass
#2	2493475-2.patch	49.67 KB	walangitan
#2

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Comment #1

walangitan CreditAttribution: walangitan as a volunteer commented 22 May 2015 at 18:44

Assigned:

Unassigned

» walangitan

I'm taking on this issue using the proposed resolutions. My goal is to to take care of these today.

Comment #2

walangitan CreditAttribution: walangitan at Chromatic commented 7 January 2016 at 17:07

File	Size
2493475-2.patch	49.67 KB

Fix the hook_help() implementation for the 23 modules listed in the issue to conform to the help standards.
Removed the @todo line in core/modules/system/src/Tests/Module/InstallUninstallTest.php and uncommented the line below it to verify that help texts have been fixed.

Comment #3

walangitan CreditAttribution: walangitan as a volunteer commented 22 May 2015 at 19:47

Status:

Postponed

» Needs review

Comment #4

jhodgdon

she/her

English

CreditAttribution: jhodgdon commented 22 May 2015 at 21:28

Status:

Needs review

» Postponed

walangitan: Thanks for the patch! Hopefully we can use it when the time comes... But for now, please see the issue summary... This issue was postponed until the blocking issues are taken care of.

Comment #5

walangitan CreditAttribution: walangitan as a volunteer commented 22 May 2015 at 21:53

jhodgdon: No worries! I'm following those other issues now as well and can create an updated patch when the blocking issues are taken care of.

Comment #6

jhodgdon

she/her

English

CreditAttribution: jhodgdon commented 22 May 2015 at 22:42

Perfect, thanks!

Comment #7

6 September 2015 at 18:59

Status:

Postponed

» Needs review

ifrik queued 2: 2493475-2.patch for re-testing.

Comment #8

6 September 2015 at 19:01

Status:

Needs review

» Needs work

The last submitted patch, 2: 2493475-2.patch, failed testing.

Comment #9

ifrik

she/her

CreditAttribution: ifrik commented 6 September 2015 at 21:16

Assigned:	walangitan	» Unassigned
Status:	Needs work	» Needs review

File	Size
2493475-9.patch	38.05 KB
8.0.x: PHP 5.5 & MySQL 5.5 13,903 pass

The last patch didn't apply anymore because since then some help texts already got changed.
The last patch also included code from the changed test.

This patch now only includes the changes to the help texts. I've also tested by un-commenting line 257 of the InstallUninstallTest patch in #2488032. There were no fails for the help texts.
Therefore, when this is committed, the additional test for help texts in the InstallUninstall test can be uncommented.

Comment #10

ifrik

she/her

CreditAttribution: ifrik commented 14 September 2015 at 20:03

Issue tags:

+Barcelona2015

Comment #11

XaviP CreditAttribution: XaviP commented 22 September 2015 at 07:33

Status:

Needs review

» Reviewed & tested by the community

2 files were hidden/shown/deleted

File	Size
2493475-2.patch	49.67 KB

2493475-9.patch	38.05 KB
8.0.x: PHP 5.5 & MySQL 5.5 13,903 pass

Reviewed patch #9:

All links to online documentation in help of the modules listed in issue summary follow the standard:
see the <a href="...">online documentation for the [Name] module</a>."
Since the patch in #2488032: Integrate help test into module uninstall test it's not commited, I cannot uncomment the line for activating the test in core/modules/system/src/Tests/Module/InstallUninstallTest.php
As the main goal of this issue is achieved, I mark it as RTBC. Sorry if I don't understand propertly how it must work.

Comment #12

22 September 2015 at 09:18

ifrik queued 9: 2493475-9.patch for re-testing.

Comment #13

22 September 2015 at 09:33

Status:

Reviewed & tested by the community

» Needs work

The last submitted patch, 9: 2493475-9.patch, failed testing.

Comment #14

ifrik

she/her

CreditAttribution: ifrik commented 22 September 2015 at 10:12

This is probably caused by #2560783: Replace !placeholder with :placeholder for URLs in hook_help() implementations

Comment #15

XaviP CreditAttribution: XaviP commented 22 September 2015 at 14:45

Status:

Needs work

» Needs review

File	Size
2493475-15.patch	38.05 KB
8.0.x: PHP 5.5 & MySQL 5.5 13,907 pass

Just find&replace "!" for ":" in patch #9, and the patch can be applied :-) Waiting for the test...

Comment #16

ifrik

she/her

CreditAttribution: ifrik commented 22 September 2015 at 14:44

File	Size
2493475-online-docs-15.patch	29.05 KB
8.0.x: PHP 5.5 & MySQL 5.5 13,907 pass

1 file was hidden/shown/deleted

File	Size
2493475-15.patch	38.05 KB
8.0.x: PHP 5.5 & MySQL 5.5 13,907 pass

Thanks xavip for the earlier review.

The placeholders in the links were replaced, so I re-rolled the patch.

Comment #17

ifrik

she/her

CreditAttribution: ifrik commented 22 September 2015 at 14:45

Oeps.... that looks like we've both done the same at the same time.

Comment #18

XaviP CreditAttribution: XaviP commented 22 September 2015 at 15:42

Ups, sorry for crossposting, I just found an easy way to update the patch. Waiting for the test.

Comment #19

ifrik

she/her

CreditAttribution: ifrik commented 22 September 2015 at 16:02

File	Size
2493475-18.patch	36.14 KB
8.0.x: PHP 5.5 & MySQL 5.5 13,985 pass

Xavid, sorry my posting seem to have stop your test.

Anyway, I've taken the filter module out of your patch, because there is an RTBC'd issue that also changes the filter.module file and fixes the link to the online documentation.

Utrecht

CreditAttribution: batigolix as a volunteer commented 23 September 2015 at 14:42

Status:

Needs review

» Reviewed & tested by the community

I reviewed the patch, applied the patch manually, checked the results in a local dev website. All seems to be OK.

Comment #23

XaviP CreditAttribution: XaviP commented 23 September 2015 at 14:45

Review of patch 2493475-18.patch in comment #19: everything ok.
Corrections in filter module are moved to #2570359: Update the hook_help for the filter module again

Comment #24

alexpott

he/they

English

🇪🇺🌍

CreditAttribution: alexpott at Chapter Three commented 26 September 2015 at 14:01

Status:

Reviewed & tested by the community

» Fixed

Committed 7599b05 and pushed to 8.0.x. Thanks!

Comment #25

26 September 2015 at 14:01

alexpott committed 7599b05 on 8.0.x

Issue #2493475 by ifrik, walangitan, XaviP, jhodgdon, batigolix: Fix...

Comment #26

10 October 2015 at 14:04

Status:

Fixed

» Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.

Fix online docs references in Help to conform to our standards

Problem/Motivation

Proposed resolution

Remaining tasks

User interface changes

API changes

Beta phase evaluation

Comments

Parent issue

Related issues