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 |
---|---|---|---|
#20 | interdiff.txt | 3.63 KB | batigolix |
#20 | text-updated_help_d8-documentation.2091461-20.patch | 4.17 KB | batigolix |
#18 | text-updated_help_d8-documentation.2091461-18.patch | 4.17 KB | ifrik |
#18 | interdiff-2091461-15-18.txt | 1.99 KB | ifrik |
#16 | text-updated_help_d8-documentation.2091461-15.patch | 4.16 KB | ifrik |
Comments
Comment #1
petrpo CreditAttribution: petrpo commentedTrying to correct it according to standards
Comment #2
petrpo CreditAttribution: petrpo commentedComment #3
berkas1 CreditAttribution: berkas1 commentedLooks OK
Comment #4
ifrikI'll work further on this to bring it inline with other field modules.
Comment #5
jhodgdonYes, this still needs work. Check out the help for the Link or Telephone modules for examples.
Comment #6
ifrikYes, I was just on it right now :)
Lots of the options that were available in D7 have been removed: it's not possible anymore to choose between field with or without summaries etc.
The text formats page changes it's name depending on whether the text editor module is enabled or not - but since it is now impossible to disable a module in D8, this module is enabled by default, so we might just as well refer to the page as "Text formats and editors".
Comment #7
jhodgdonYes, it is impossible to *disable* a module, but you can still *uninstall* a module. But I think it's probably OK to leave that reference as it is.
Anyway, this mostly looks good! A few typographical/grammatical fixes would help:
a)
formated -> format
b)
Extra space in the A link text.
c) "formated" is misspelled. Should be "formatted".
d) Heading "Setting and display the text length"... This doesn't make sense to me. Reading what is in that item, maybe it should be just "Setting the text length"?
e)
You can change the number of characters that define the maximum text length
This could be simplified to say "You can set the maximum text length"
f)
can be entered on the <em>Manage
Extra space before the EM tag.g) I do not think it is clear in the last Uses point what the difference is between the maximum text length and the size of the form field.
h)
choose whether to displayed a trimmed version of the text, and if so after how many characters the text should be cut off.
- displayed -> display
- And that last phrase... would be better as "and if so, where to cut off the text"
Comment #8
ifrikThanks for the comments.
In the last item, I wanted to explain that changing the length of the form doesn't impact on the allowed text length - but thinking about it: that's a general issue that needs to be explained in the field help pages.
Comment #9
jhodgdonThe patch file is empty. Can you re-upload?
Comment #10
ifriknot sure what happened there but here it is again
Comment #11
jhodgdonSo... In reading this one more time, I'm a bit concerned about the first line of About. I think we should list the actual field types rather than saying "various" maybe? List the names someone would see in the Field UI and maybe add a brief explanation of what each one is? I don't know... it is possibly OK as it is.
Other than that... looks pretty good! I noticed a typo:
"You can set change the maximum text length"
And the Text with Summary field has some additional options that should maybe be described?
Comment #12
ifrikI added more specific details on long text fields and on summaries. Therefore I also changed the order of the items.
Due to a bug, the text editor is not displayed on the short text field: #2143085: No text editor displayed for Text field. I assume that the text editor is supposed to work the same on the short and long fields, but this should be checked again nonetheless.
Comment #13
ifrikComment #14
jhodgdonThis help text overall seems very good to me! There are a few minor grammatical things that need fixing in this patch:
a) This sentence no verb (start of About):
"The Text module allows you to short and long text fields with optional summaries."
b) In Uses item 1:
"If you choose Text as field type on the Manage fields page,"
needs "the" before "field type"
c) Uses item 2:
" you can set the number of rows that is displayed to users."
is -> are
d) Uses item 4:
"choose whether to display a trimmed version of the text, and if so, where to cut off the text."
Normally I think "whether" should have an alternative, so it should be "whether ... or ...", but there is no "or" alternative given. Maybe just leave out the word "whether"?
e) Uses item 5:
"In order to display a summary that is different from the trimmed beginning of text"
This seems very awkward to me. Maybe:
"As an alternative to using a trimmed version of the text, you can choose to enter a separate summary by ..."
f) Uses item 5:
"by choosing the appropriate format on the Manage Display page."
There is an extra space between "the" and "appropriate"
g) Last Uses item:
"by choosing Plain text as Format on the Manage Display page."
Needs "the" before "Format".
Comment #15
ifrikComment #16
ifrikThanks for the comments. I've included them.
Comment #17
jhodgdonExcellent!
One thing:
As an alternative to using a trimmed version of the text, you can enter a separate summary by choosing the Long text with summary format on the Manage Fields page.
I don't think this is a "format" -- isn't it a "field type"?
Other than this small thing, I think this is ready to go (it will still need a manual test however). Thanks!
Comment #18
ifrikSo many managing pages... yes, that should have been field type. I've changed it.
Comment #19
jhodgdonExcellent, thanks! I think this is ready for someone to give it a manual test:
- Verify that the formatting is good.
- Verify that all the links work.
- Verify that where specific page names, tab names, labels, etc. are mentioned in the help text, they match what a user actually sees on the screen.
Comment #20
batigolix- formatting is good
- all the links work.
- specific page names, tab names, labels, etc. are correct but I had to change the case to make them match correctly
Comment #23
jhodgdon20: text-updated_help_d8-documentation.2091461-20.patch queued for re-testing.
Comment #24
jhodgdonLooks good, thanks! Assuming the tests pass this time (the failure seemed to be totally unrelated), I think this is ready to go in.
Comment #25
jhodgdonThanks again everyone! Committed to 8.x.