Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.
Background:
This issue is part of the task to update the hook_help texts of the Drupal 8 modules:
#1908570: [meta] Update or create hook_help() texts for D8 core modules
Tasks:
- review / write the hook_help text according to help guidelines
Comment | File | Size | Author |
---|---|---|---|
#27 | interdiff.txt | 2.66 KB | jhodgdon |
#27 | 2091363-system-help-27.patch | 16.84 KB | jhodgdon |
Comments
Comment #1
jhodgdonNote: The File and Image module help is soon going to be expecting that the System module help includes an explanation of private vs. public file storage, and how to configure this. When this help text is reviewed/updated, can you make sure file storage is covered?
Comment #2
surendramohan CreditAttribution: surendramohan commentedSelf-assigning: Working on it.
Comment #3
surendramohan CreditAttribution: surendramohan commentedPatch description:
Added help entry for public and private file system.
Comment #4
lostkangaroo CreditAttribution: lostkangaroo commentedComment #5
lostkangaroo CreditAttribution: lostkangaroo commentedWith a quick glance I noticed that the string tokens were using @ rather then !. These will need to be fixed as well as updating any url calls following the guidelines listed on this page https://drupal.org/node/632280. Once these are fixed I would be happy to do a full review for you.
Comment #6
surendramohan CreditAttribution: surendramohan commentedI appreciate your suggestions.
I have updated all sections of hook_help matching D8 coding standards.
Attached patch for your reference.
Comment #7
lostkangaroo CreditAttribution: lostkangaroo commentedThere looks to be a blocker for this dealing with module management so marking this postponed until #2035079: [PP-3] Figure out what to do with the install/uninstall modules page can be resolved. This will have an impact on the managing modules section which is not reviewed below.
A few nit picks unfortunately, most of which date back several versions of Drupal.
You certainly picked a good one and for that you are appreciated.
Comment #8
lostkangaroo CreditAttribution: lostkangaroo commented#2109553: Add route to resolve update.php path allows the use of routes now to replace $base_url in resolving update.php links and removes the dependency on using the global.
Comment #9
surendramohan CreditAttribution: surendramohan commentedThanks a lot for your valuable feedback and suggestions (which is always appreciated at my end).
I will figure out the changes and update you with the latest patch version shortly.
Comment #10
ifrikIn the issue queue #2031177: Improve help for file module it was proposed to move a section about public and private files into the system help:
Comment #11
jhodgdonWe just had a change to hook_help, on this issue: #2183113: Update hook_help signature to use route_name instead of path.
Here is the change record: https://drupal.org/node/2250345
This patch will need a reroll for this change.
Comment #12
jhodgdonAnother thing to add to the "this is in system module" help: The System module provides the System Help block, which displays help at the top of admin pages. It also adds this help to system dialogs.
Comment #13
batigolixComment #14
jhodgdonI don't think this should be postponed.
Instead of having one critical parent issue I have been asked to change the status of each child issue.
This one seems Major to me. The System module has a lot of stuff that is poorly or not documented right now.
Comment #15
jhodgdonRegarding stuff above...
- The Help block is back in the Help module now.
- We still need info about the file system.
- Image toolkit is also part of System module. Suggested help, which I was just about to add to the Image module on #2091337: Update hook_help for Image module but this is really in System:
Comment #16
jhodgdonOK... In the interest of getting the hook_help() patches DONE, I decided to make a new patch for this one. The old patch was long outdated, so I pretty much had to start over. No interdiff, sorry.
Some notes:
a) I only worked on the main help topic page. The changes in the rest of the hook_help() [the page help sections] were just to replace @url with !url. So... We should eventually take a look at this page-level help and revise it; however, that is a separate issue. See #2265533: Review page-level help and make sure it's conceptual
b) I tried to make all of the help text as clear and concise as possible, so nearly all of it has been rewritten. I also changed the order of the Uses topics slightly, trying to put the most important ones near the top and put related topics near each other.
c) As a technicality... Most of the functionality of the System module is now that it provides a UI for functionality that is part of Drupal Core. This is reflected in the About section -- it really isn't true any more that the System module provides a lot of base functionality -- mostly it's just the UI for configuring that functionality, as well as the admin/* menu structure (Structure, Configure, etc.).
Comment #18
ifrikThe link to the online documentation links to a page with the expected path, but the page is about setting up cron and caching in Drupal 6.
We could either move the content of that site, and use https://www.drupal.org/documentation/modules/system for the help for the system module, or make a different page.
I notice that "Drupal" is used several times. Did I miss a policy change about that?
For the rest all the text looks good. If we decide to move the D6 cron documentation to a different page then this could be RTBC'ed
Comment #19
jhodgdonThat is the right link to the online documentation. The page starts:
The system module provides system-wide defaults for running jobs at particular times, storing (caching) web pages to improve efficiency, and performing other essential tasks. The module also keeps track of various preferences you give for how you want your system to behave.
See, it's about the System module... :) it probably needs updating for Drupal 7/8.
I don't know of a policy about not mentioning the word Drupal in the help... do we have one?
Comment #20
gvsoPatch in #16 seems to be fine for me, RTBC +1
Comment #21
jhodgdonOh, you're right about not using "Drupal":
"Use 'Site', not 'Drupal'. Referring to Drupal by name complicates distributions and users may not know the site is running on Drupal."
This is from https://www.drupal.org/node/604342
So this needs a new patch.
Comment #22
gvso@ifrik @jhodgdon I do understand your point but how can we change that? I don't think that "The site comes with a number of core modules" will sound better than "Drupal comes with a number of core modules".
Comment #23
ifrikUnfortunately it is not about what sounds better, but about what works for users.
This help texts are part of core that can - and is - used in different distributions, so therefore some users don't have "a Drupal site" - but what they have in any case will be "your site" or "the system".
We have been consistent about that in other cases as well.
The only times where we used "Drupal" is when it refers to something like "drupal.org" or "Drupal's translation server" because that is still called Drupal, even when you use a different distribution.
Comment #24
jhodgdonSo, the existing patch says:
Drupal comes with a number of core modules; each module provides a discrete set of features and may be installed or uninstalled depending on the needs of the site.
We can change this to something like this:
Depending on which distribution or installation profile you choose when you install your site, several modules are installed and others are provided but not installed. Each module provides a discrete set of features; modules may be installed or uninstalled depending on the needs of the site.
We'll need to make a similar change in the Themes section too. The current patch says:
Drupal comes packaged with several core themes, and additional contributed themes are available at the ...
We can change this to something like:
Depending on which distribution or installation profile you choose when you install your site, a default theme is installed, and possibly a different theme for administration pages. Other themes are provided but not installed, and additional contributed themes are available...
Thoughts?
Comment #25
jhodgdonOK. Here's a new patch:
- Rerolled (the last patch didnt' apply). The interdiff is after the reroll.
- Changed "Drupal" references as discussed above, except where they referred to "the Drupal community" or "Drupal.org".
- Updated drupal.org links to be https://www.drupal.org instead of http://drupal.org
Comment #27
jhodgdonWhoops. Route change. Fixing patch.
Comment #28
ifrikAll links work and have the correct labels.
The text reads well.
As far as I see everything that is controlled by the system module is covered.
Comment #29
webchickExcellent work!
Committed and pushed to 8.0.x. Thanks!