[drupal-devel] [task] Improve helpsystem and helptexts

stefan nagtegaal drupal-devel at drupal.org
Tue Apr 19 20:57:25 UTC 2005


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

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



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




------------------------------------------------------------------------

April 19, 2005 - 09: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 - 13: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 - 14: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.




------------------------------------------------------------------------

April 19, 2005 - 21:36 : drumm

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.







More information about the drupal-devel mailing list