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 |
---|---|---|---|
#22 | drupal8.breakpoint-module.2091297-22.patch | 5.12 KB | batigolix |
#22 | interdiff.txt | 4.18 KB | batigolix |
#19 | drupal8.breakpoint-module.2091297-19.patch | 5.3 KB | batigolix |
#19 | interdiff.txt | 5.64 KB | batigolix |
#17 | interdiff.txt | 3.5 KB | batigolix |
Comments
Comment #1
lostkangaroo CreditAttribution: lostkangaroo commentedTokenized the links and added a link to the DO Handbook Page.
Comment #2
lostkangaroo CreditAttribution: lostkangaroo commentedComment #3
batigolixI changed the reference to the handbook to be more conform the standard example (https://drupal.org/node/632280)
And changed the tokens from @something to !something, because I think that is the standard now (I'm a bit confused about this)
I also doubt about the points in the Uses section. Normally we would list action for the site builder here, but the breakpoint has no UI. So not sure if we should list all these options here ...
Comment #4
lostkangaroo CreditAttribution: lostkangaroo commentedI had some worries about the breakpoint UI also since the handbook page lists a possible module in the works. Thanks for fixing the @'s as someone pointed out to me recently in IRC that even remote links should be fine to not be passed through checkplain as long as they are in code.
Will mark RTBC as soon as it passes testing. Good Job!
Comment #5
batigolixI would like some more feedback from others (especially about the Uses section) before marking this RTBC.
Comment #7
lostkangaroo CreditAttribution: lostkangaroo commentedI don't think it will be necessary to wait honestly based on the discussions about hook_help text when it originally went in #1734642-158: Move breakpoint module into core. In this case we really only need to update the links.
Comment #8
lostkangaroo CreditAttribution: lostkangaroo commented#3: drupal8.breakpoint-module.2091297-3.patch queued for re-testing.
Comment #9
jhodgdonThanks!
Could we make the formatting here more uniform in Uses? One of the Uses items uses DT/DD/P, and the other uses DT/DD/DD. Let's just use multiple DD tags instead of P tags?
I also think that the Wikipedia link should not be taken out of the t() string. If you'll notice, there is an "en" in the URL, meaning it's going to an English page. If you leave the link in, then translators can switch that to a link appropriate for their language.
Comment #10
batigolixThe formatting seems pretty standard to me: http://jsfiddle.net/mLghm/
There is just one DL that contains two paragraphs P
The patch fixes the Wikipedia link.
Comment #11
jhodgdonPoint taken. I think this is ready! It needs a quick manual test:
- Make sure the links all work.
- Make sure the formatting is OK.
Normally I would say we would need to make sure that all UI text matches what you see in the UI, but this module doesn't have a UI.
Comment #12
jhodgdonCome to think of it... Do you think we should mention explicitly in the help that the module has no UI? Other modules that do not have UI say something about that in their help.
Comment #13
batigolixIt doesnt hurt to mention it.
There is a UI in contrib, though.
We have a similar situation with the tour module. No UI a contrib module exists that lets you create tours via the UI.
I am not sure if it is a good idea to explicitly link from hook_help to the contrib modules project page in such cases, as we have no idea if these modules will be usable when D8 launches (although there is plenty of time left ;). Or if a much better contrib module is available that we do not know of yet.
The help text of the taxonomy module (typically an area with plenty of contrib activity) mentions:
There are <a href="@taxcontrib">many contributed modules</a> that extend the behavior of the Taxonomy module for both display and organization of terms
.Maybe something similar could be added in this help text?
Other remaining tasks:
- Make sure the links all work.
- Make sure the formatting is OK. (as mentioned in #11)
Comment #14
jhodgdonRegarding contrib modules, we did suggest particular contrib modules in some of the D7 help pages too, though I cannot remember exactly what... maybe Token? So I think that is fine, especially if you say "Contributed modules such as (link)Breakpoint UI(end link) may provide a user interface." (In this case, linking to that particular module sounds like a good idea, but leaving it open that there might be others is also a good idea).
Comment #15
batigolixJust adding a note that the help should make clear that breakpoints are defined in the theme configuration
Comment #16
jhodgdonstatus as per last few comments
Comment #17
batigolixThis patch adds the link to the contrib module and explicitly mentions configuration.
I am still not really convinced about this help text.
Here we have the situation of a new core module with a maintainer that actually made an effort to write a hook_help text. In contrast to many other new modules where we start with nothing.
This takes us back to the pre-D7 times where some help text were well and others were minimally written. There was little consistency.
Since D7 we have much more consistent help text and I feel the text in the current patch does not fit in very well with the rest. The Uses section contains points that are not actually possible actions for site administrators. They are theory about Breakpoints.
I feel all of the current proposal text could be compressed into one (long) About section.
Comment #18
jhodgdonI agree with the assessment in #17. We normally reserve the "Uses" section for things a user can do in the UI, and this module has no UI.
How about this for a proposed re-organization? I think all the info there is great and we just need to present it in a manner more like our standard:
- About
(include the paragraph from the current patch)
-- h4 Terminology
DT Breakpoint
DD (define what a breakpoint is)
DT Media query
DD (definition)
DT Resolution multiplier
DD (definition)
DT Breakpoint group
DD (definition
- Uses
DT Defining breakpoints and breakpoint groups
DD Modules and themes can use the API provided by the Breakpoint module to define breakpoints and breakpoint groups, and to assign resolution multipliers to breakpoints. For more information, see https://drupal.org/node/1803874
[Note: I hope this notation is clear... I'm suggesting that we have an H4 header within About called "Terminology", and that it contain a DL list of terms, and that we have only one item in Uses.]
Comment #19
batigolixThat is a good idea.
In this patch I restructured the text according to the outline in #18
I did not (have/take) time to review properly.
One other question remains:
The More info link you suggested for the Uses section was already in the About section. We want 2 x the same link in this help?
Comment #20
jhodgdonI think you're right that the more information link only needs to be in one place. I didn't realize that was the same page as documentation/modules/breakpoint probably, but you're right, it is. I think that the new format reads well, and I didn't see any typos or grammatical problems.
So other than removing the duplicate link, I think this is ready to go, aside from a manual test that would:
- Verify that all the links work
- Verify that the formatting is OK.
Comment #21
lostkangaroo CreditAttribution: lostkangaroo commentedWas just about to do the manual and found a whitespace error in the patch at the end of Line 30.
Comment #22
batigolixThere we go.
- removed trailing white space
- removed 2nd link to docs
- corrected name of module (was "Breakpoints")
Comment #23
jhodgdonThanks! Time for a manual test then.
Comment #24
robcarrText seems good and useful links to more detailed documentation. Changing to RTBC.
Comment #25
batigolixThis needs a manual test first:
- Verify that all the links work
- Verify that all mentions of pages/text within the UI match what is seen in the UI
- Verify that the formatting is OK.
Comment #26
batigolixComment #27
jhodgdonI gave this a manual review today and it all looks good!
Comment #28
jhodgdonThanks again everyone! Committed to 8.x.