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

Tue Apr 19 12:21:36 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:   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.