Issue status update for http://drupal.org/node/20760 Project: Drupal Version: cvs Component: base system Category: tasks Priority: normal Assigned to: stefan nagtegaal Reported by: stefan nagtegaal Updated by: adrinux Status: patch -1 on removing the help texts. I personally have found them useful on several occassions, the short text is useful for telling you what to do on a given page, but it's the long help text that can be helpful to understand how - for instance - the permissions or taxonomy systems work. As a compromise they could perhpas be moved to drupal.org and linked from within Drupal, but it's a lot harder for people to provide 'patches' for content on drupal.org, and makes translation a real problem. Removing them because they're out of date doesn't really address the issue. adrinux Previous comments: ------------------------------------------------------------------------ April 18, 2005 - 14:16 : stefan nagtegaal Attachment: http://drupal.org/files/issues/helptext-removal.diff (89.03 KB) I know of you guys are falling from their chair when seeing this patch, but... The attached patch removes all long helptexts which are used by the help.module to display them. I - and i know there are more people who thinks about that the same way - believe that, with a good CMS these kind of very long helptexts are not needed. I would prefer to improve the short helptexts on top of every page, instead of these longer versions. The documentation team already started to improve these short texts, to reflect what people could do on a certain page.. Another reason to delete these helptexts was that there were almost none of the translators who translated them. I'm not sure if that is because the text is too large, or the info is outdated.. But, i think it would be better to remove these... See also the related thread here: http://lists.drupal.org/archives/drupal-docs/2005-04/msg00008.html By applying this patch, the help.module will be deprecated... :-) ------------------------------------------------------------------------ April 18, 2005 - 15:01 : Uwe Hermann Hm, I'm not sure whether the help texts should be removed altogether, but making them shorter and more concise is definately a good thing.

Issue status update for http://drupal.org/node/20760 Project: Drupal Version: cvs Component: base system Category: tasks Priority: normal Assigned to: stefan nagtegaal Reported by: stefan nagtegaal Updated by: stefan nagtegaal Status: patch Hmmm... The HTML-filter filtered all the <p>-tags out of the above post.. Again: Pro's: - we move all the <p>-tags from the translation templates, by handling them inside drupal_get_help(); Known side effects: The lists inside the helptext are also wrapped inside <p>-tags, which result in: '<ul><li><p>'. $text .'</p></li></ul>'; stefan nagtegaal Previous comments: ------------------------------------------------------------------------ April 18, 2005 - 16:16 : stefan nagtegaal Attachment: http://drupal.org/files/issues/helptext-removal.diff (89.03 KB) I know of you guys are falling from their chair when seeing this patch, but... The attached patch removes all long helptexts which are used by the help.module to display them. I - and i know there are more people who thinks about that the same way - believe that, with a good CMS these kind of very long helptexts are not needed. I would prefer to improve the short helptexts on top of every page, instead of these longer versions. The documentation team already started to improve these short texts, to reflect what people could do on a certain page.. Another reason to delete these helptexts was that there were almost none of the translators who translated them. I'm not sure if that is because the text is too large, or the info is outdated.. But, i think it would be better to remove these... See also the related thread here: http://lists.drupal.org/archives/drupal-docs/2005-04/msg00008.html By applying this patch, the help.module will be deprecated... :-) ------------------------------------------------------------------------ April 18, 2005 - 17:01 : Uwe Hermann Hm, I'm not sure whether the help texts should be removed altogether, but making them shorter and more concise is definately a good thing. ------------------------------------------------------------------------ April 18, 2005 - 18:57 : adrinux -1 on removing the help texts. I personally have found them useful on several occassions, the short text is useful for telling you what to do on a given page, but it's the long help text that can be helpful to understand how - for instance - the permissions or taxonomy systems work. As a compromise they could perhpas be moved to drupal.org and linked from within Drupal, but it's a lot harder for people to provide 'patches' for content on drupal.org, and makes translation a real problem. Removing them because they're out of date doesn't really address the issue. ------------------------------------------------------------------------ April 18, 2005 - 20:36 : drumm This would be an easy way to make http://drupal.org/node/11958 possible to commit. Although there is still the hard way of making that work which involves menu system hacking. I'm neutral on this patch. ------------------------------------------------------------------------ April 19, 2005 - 09:54 : stefan nagtegaal Attachment: http://drupal.org/files/issues/drupal-help-user.diff (10.94 KB) See the attached patch which does the following: - adds 2 functions to common.inc resp. drupal_get_help() and drupal_set_help(); - brings the helptext on the same level of usage as drupal_(set|get)_message() and drupal_(set|get)_titlle(), which makes the code a little more consistent; - moves the help-messages to the functions which returns the output of a page; - get's rid of the -tags in the translation templates and moved the to a central place where we can extend it to make them easily themeable; - we pass long helptexts by doing the following: <?php   $help[] = t('first paragraph of text.');   $help[] = t('second paragraph of text');   drupal_set_help($help); ?> or directly when returning a short helpmessage, by doing: <?php   drupal_set_help(t('helptext')); ?> I patched the user.module and the chameleon.theme to reflect the changes. Known side effects: - the lists in the helptexts are wrapped inside ' '. $text .' ' either, which should be omitted, not sure howto yet. Any idea's? I would really like to know wha you guys think about this.. Please share your thoughts...

Issue status update for http://drupal.org/node/20760 Project: Drupal Version: cvs Component: base system Category: tasks Priority: normal Assigned to: stefan nagtegaal Reported by: stefan nagtegaal Updated by: moshe weitzman Status: patch to me, this patch represents an engineer's lazy way to fix a problem. If the help texts are not helpful anymore, then fix the bad ones. this is throwing out the baby with the bath water. if these texts are a pain to translate, then *don't translate them*. I can't believe that even needs saying, but you did list this as a benefit of the patch. hook_help() allows any module to inject help text on any page. thats a highly useful feature, which we employ for compose tips and various other things. see the helpedit.module in Contrib ... so this patch does not deprecate hook_help at all. we already have a non-php way to do a file description and other metadata. it is Doxygen syntax. it needs better documentation and more examples so that module developers use it more. moshe weitzman Previous comments: ------------------------------------------------------------------------ April 18, 2005 - 09:16 : stefan nagtegaal Attachment: http://drupal.org/files/issues/helptext-removal.diff (89.03 KB) I know of you guys are falling from their chair when seeing this patch, but... The attached patch removes all long helptexts which are used by the help.module to display them. I - and i know there are more people who thinks about that the same way - believe that, with a good CMS these kind of very long helptexts are not needed. I would prefer to improve the short helptexts on top of every page, instead of these longer versions. The documentation team already started to improve these short texts, to reflect what people could do on a certain page.. Another reason to delete these helptexts was that there were almost none of the translators who translated them. I'm not sure if that is because the text is too large, or the info is outdated.. But, i think it would be better to remove these... See also the related thread here: http://lists.drupal.org/archives/drupal-docs/2005-04/msg00008.html By applying this patch, the help.module will be deprecated... :-) ------------------------------------------------------------------------ April 18, 2005 - 10:01 : Uwe Hermann Hm, I'm not sure whether the help texts should be removed altogether, but making them shorter and more concise is definately a good thing. ------------------------------------------------------------------------ April 18, 2005 - 11:57 : adrinux -1 on removing the help texts. I personally have found them useful on several occassions, the short text is useful for telling you what to do on a given page, but it's the long help text that can be helpful to understand how - for instance - the permissions or taxonomy systems work. As a compromise they could perhpas be moved to drupal.org and linked from within Drupal, but it's a lot harder for people to provide 'patches' for content on drupal.org, and makes translation a real problem. Removing them because they're out of date doesn't really address the issue. ------------------------------------------------------------------------ April 18, 2005 - 13:36 : drumm This would be an easy way to make http://drupal.org/node/11958 possible to commit. Although there is still the hard way of making that work which involves menu system hacking. I'm neutral on this patch. ------------------------------------------------------------------------ April 19, 2005 - 02:54 : stefan nagtegaal Attachment: http://drupal.org/files/issues/drupal-help-user.diff (10.94 KB) See the attached patch which does the following: - adds 2 functions to common.inc resp. drupal_get_help() and drupal_set_help(); - brings the helptext on the same level of usage as drupal_(set|get)_message() and drupal_(set|get)_titlle(), which makes the code a little more consistent; - moves the help-messages to the functions which returns the output of a page; - get's rid of the -tags in the translation templates and moved the to a central place where we can extend it to make them easily themeable; - we pass long helptexts by doing the following: <?php   $help[] = t('first paragraph of text.');   $help[] = t('second paragraph of text');   drupal_set_help($help); ?> or directly when returning a short helpmessage, by doing: <?php   drupal_set_help(t('helptext')); ?> I patched the user.module and the chameleon.theme to reflect the changes. Known side effects: - the lists in the helptexts are wrapped inside ' '. $text .' ' either, which should be omitted, not sure howto yet. Any idea's? I would really like to know wha you guys think about this.. Please share your thoughts... ------------------------------------------------------------------------ April 19, 2005 - 02:58 : stefan nagtegaal Hmmm... The HTML-filter filtered all the <p>-tags out of the above post.. Again: Pro's: - we move all the <p>-tags from the translation templates, by handling them inside drupal_get_help(); Known side effects: The lists inside the helptext are also wrapped inside <p>-tags, which result in: '<ul><li><p>'. $text .'</p></li></ul>'; ------------------------------------------------------------------------ April 19, 2005 - 06:34 : adrian I think this is a great idea for consistency .. One of the things I would like to see done, is to move the description field out of the module, and into an external module.dsc text file, which would use a simple format such as : --- description: Do some cool new thing. --- Which would mean you don't need to load the module to get the description (or other meta-information). This would remove the need for the _help hook.

Issue status update for http://drupal.org/node/20760 Project: Drupal Version: cvs Component: base system Category: tasks Priority: normal Assigned to: stefan nagtegaal Reported by: stefan nagtegaal Updated by: drumm Status: patch I think drupal_(get|set)_help() functions are an excellent idea. Changing the way p tags are handled seems like an unnecessary change which breaks more than it fixes. Putting multiple paragraphs in an array doesn't seem right for some reason. drupal_set_help() could still be called from hook_menu() or hook_init() to put arbirtrary help text on arbitrary pages. drumm Previous comments: ------------------------------------------------------------------------ April 18, 2005 - 08:16 : stefan nagtegaal Attachment: http://drupal.org/files/issues/helptext-removal.diff (89.03 KB) I know of you guys are falling from their chair when seeing this patch, but... The attached patch removes all long helptexts which are used by the help.module to display them. I - and i know there are more people who thinks about that the same way - believe that, with a good CMS these kind of very long helptexts are not needed. I would prefer to improve the short helptexts on top of every page, instead of these longer versions. The documentation team already started to improve these short texts, to reflect what people could do on a certain page.. Another reason to delete these helptexts was that there were almost none of the translators who translated them. I'm not sure if that is because the text is too large, or the info is outdated.. But, i think it would be better to remove these... See also the related thread here: http://lists.drupal.org/archives/drupal-docs/2005-04/msg00008.html By applying this patch, the help.module will be deprecated... :-) ------------------------------------------------------------------------ April 18, 2005 - 09:01 : Uwe Hermann Hm, I'm not sure whether the help texts should be removed altogether, but making them shorter and more concise is definately a good thing. ------------------------------------------------------------------------ April 18, 2005 - 10:57 : adrinux -1 on removing the help texts. I personally have found them useful on several occassions, the short text is useful for telling you what to do on a given page, but it's the long help text that can be helpful to understand how - for instance - the permissions or taxonomy systems work. As a compromise they could perhpas be moved to drupal.org and linked from within Drupal, but it's a lot harder for people to provide 'patches' for content on drupal.org, and makes translation a real problem. Removing them because they're out of date doesn't really address the issue. ------------------------------------------------------------------------ April 18, 2005 - 12:36 : drumm This would be an easy way to make http://drupal.org/node/11958 possible to commit. Although there is still the hard way of making that work which involves menu system hacking. I'm neutral on this patch. ------------------------------------------------------------------------ April 19, 2005 - 01:54 : stefan nagtegaal Attachment: http://drupal.org/files/issues/drupal-help-user.diff (10.94 KB) See the attached patch which does the following: - adds 2 functions to common.inc resp. drupal_get_help() and drupal_set_help(); - brings the helptext on the same level of usage as drupal_(set|get)_message() and drupal_(set|get)_titlle(), which makes the code a little more consistent; - moves the help-messages to the functions which returns the output of a page; - get's rid of the -tags in the translation templates and moved the to a central place where we can extend it to make them easily themeable; - we pass long helptexts by doing the following: <?php   $help[] = t('first paragraph of text.');   $help[] = t('second paragraph of text');   drupal_set_help($help); ?> or directly when returning a short helpmessage, by doing: <?php   drupal_set_help(t('helptext')); ?> I patched the user.module and the chameleon.theme to reflect the changes. Known side effects: - the lists in the helptexts are wrapped inside ' '. $text .' ' either, which should be omitted, not sure howto yet. Any idea's? I would really like to know wha you guys think about this.. Please share your thoughts... ------------------------------------------------------------------------ April 19, 2005 - 01:58 : stefan nagtegaal Hmmm... The HTML-filter filtered all the <p>-tags out of the above post.. Again: Pro's: - we move all the <p>-tags from the translation templates, by handling them inside drupal_get_help(); Known side effects: The lists inside the helptext are also wrapped inside <p>-tags, which result in: '<ul><li><p>'. $text .'</p></li></ul>'; ------------------------------------------------------------------------ April 19, 2005 - 05:34 : adrian I think this is a great idea for consistency .. One of the things I would like to see done, is to move the description field out of the module, and into an external module.dsc text file, which would use a simple format such as : --- description: Do some cool new thing. --- Which would mean you don't need to load the module to get the description (or other meta-information). This would remove the need for the _help hook. ------------------------------------------------------------------------ April 19, 2005 - 06:21 : moshe weitzman to me, this patch represents an engineer's lazy way to fix a problem. If the help texts are not helpful anymore, then fix the bad ones. this is throwing out the baby with the bath water. if these texts are a pain to translate, then *don't translate them*. I can't believe that even needs saying, but you did list this as a benefit of the patch. hook_help() allows any module to inject help text on any page. thats a highly useful feature, which we employ for compose tips and various other things. see the helpedit.module in Contrib ... so this patch does not deprecate hook_help at all. we already have a non-php way to do a file description and other metadata. it is Doxygen syntax. it needs better documentation and more examples so that module developers use it more.