[drupal-devel] Help system redesign

[Gerhard Killesreiter]

On Sun, 25 Sep 2005, Larry Garfield wrote:

> Wow this thread picked up steam today. :-)

I like to think that this is also due to the removal of the issues
posted to this list. :p

> To comment on all the replies to date so far, in no particular order:
>
> 1) I freely admit that my knowledge of PO files is virtually nill.
> I suppose they could serve as the delivery file format, but how many
> developers know a PO editor?  I'd never even heard of one until
> about 2 weeks ago, but have been writing PHP for over 5 years.
> Amazon insists that the Docs team will be writing all or nearly all
> of the help text anyway, but I still believe we should make it as
> easy as possible for non-Docs Team developers to write their own
> help text.  Remember, not all Drupal modules end up on drupal.org!
> I mention XML as an alternative because developers are far more
> likely to know XML than PO, I think.

Developers don't need to know anything about PO editors as long as they
aren't also translators.

> 2) I wasn't aware of the way in which translations are cached now.  If, as
> Khalid suggested, we could modify t() to handle lookups using a short key as
> well as the full English text, perhaps we could leverage the existing cache
> mechanism and let it do whatever it does?  That would be necessary to achieve
> the goal of getting big blocks o' text out of the .module file, as well as
> making the matching faster (see next).

We are currently using the English text strings directly. We could move
to using md5 checksums, if this is improves something. I guess
introducing an index on the first couple of cahracters would be helpfull
as well.

> 3) The statement that very-long string PO lookups is slow is based on comments
> killes made in the aforementioned IRC discussion.  I will take his word on it
> unless someone can show otherwise. :-)

My comment was based on the fact that long strings get retrieved
directly from the db. If the t() function is slower for long strings
than for short ones (I suspected this) needs to be proven.

> 4) I firmly believe that any new help system should be designed in
> such a way as to encourage developers to provide context sensitive
> help.  Even if most of the context sensitive help *text* is written
> by the Docs and Translation teams, developers should be encouraged
> to include the hooks for it in the first place.  I suspect they'll
> want to provide at least an effort at text for it, if only to not
> ship code that reads "help goes here", so again some
> developer-friendly way of creating said text should be included.
> Again, that's especially important for non-drupal.org modules that
> the Docs and Translation teams won't get a crack at either way.

The way to retrieve help from the databse that has been proposed in
#drupal would still allow you to hardcode translatable help texts into
the module as it is done currently.

Cheers,
	Gerhard