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

Tue Apr 19 12:36:23 UTC 2005

Moshe,

it's not very clear to me what you mean.. I think you did only look at  
the first patch was probably will never get in drupal.
But I do like your opinion as developer, so i'm curious what you think  
about the second approach took to move the help from outside _help into  
the corresponding code, like we do in more cases like  
drupal_(get|set)_title(), and drupal_(get|set)_breadcrumb()..

I know that the code for drupal_(get|set)_help() is not optimal yet,  
and does need *some* work though, but as you are one of those big  
developers which work I admire I would really appreciate your opinion..

Direct link: http://drupal.org/files/issues/drupal-help-user.diff or  
http://drupal.org/node/20760 from comment #4

Stefan.

Op 19-apr-05 om 14:21 heeft moshe weitzman het volgende geschreven:

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