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... :-)

CommentFileSizeAuthor
#4 drupal-help-user.diff10.94 KBStefan Nagtegaal
helptext-removal.diff89.03 KBStefan Nagtegaal

Comments

Uwe Hermann’s picture

Uwe Hermann commented

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.

adrinux’s picture

adrinux commented

-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.

drumm’s picture

drumm
he/him
Location NY, US
commented

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.

Stefan Nagtegaal’s picture

Stefan Nagtegaal commented
StatusFileSize
new drupal-help-user.diff10.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:

  $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:

  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...

Stefan Nagtegaal’s picture

Stefan Nagtegaal commented

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>';

adrian’s picture

adrian commented

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.

moshe weitzman’s picture

moshe weitzman commented

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.

drumm’s picture

drumm
he/him
Location NY, US
commented

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.

Stefan Nagtegaal’s picture

Stefan Nagtegaal commented

Drumm, could you please show me how todo this:
"drupal_set_help() could still be called from hook_menu() or hook_init() to put arbirtrary help text on arbitrary pages."

Moshe and Adrian just convinced me to take a whole other approach.
Maybe you can elaborate alittle more on this (maybe even with some code)?

I think I kind a lost the track on this one for now... :-(

Stefan Nagtegaal’s picture

Stefan Nagtegaal commented

Not hearded anything from Drumm, and the rest of the community is against it... Marking this issue as 'Won't fix'..