[drupal-devel] Help system redesign

[Larry Garfield]

On Saturday 24 September 2005 11:25 pm, Khalid B wrote:
> Hey Larry
>
> Thanks for taking the time to update those who do not frequent IRC on
> this important topic.
>
> Some comments:
>
> 1. Use of <link>
>
> The <link>blah</link> is not something I like to see. This is none
> standard, even though it will not make  it in the final rendered HTML
> as is. I prefer something that is syntactically valid, such as <div
> class="drupalhelp">blah</div>.
>
> A better option will be a call to a function: e.g. drupal_help('key');

Well, the problem with putting a function call into the help text is that we'd 
then have to eval() it.  I've not looked at Drupal's eval wrapper, but I 
generally shy away from eval() for security reasons.  Also, mixing PHP code 
with the help text is what we're trying to not do.

> 2. XML
> While everyone is using XML today, and it is very much in vogue, do we
> really needed? Wouldn't a simple:
>
> key1:text goes here
> key2:other text goes here
>
> Be just as adequate?

Probably.  As long as it's easily hand-editable it should work fine.  I 
suggested XML because of the plethora of editing tools available and it's 
good design vis a vis escape-needing characters.  A colon-delimited text file 
or some such would work too, as long as we handle escaping of real colons in 
the string.

> 3. .po files
>
> Where are the .po in all this? If we are using a modulename.es.help,
> will that contain the help only, or all the strings? If it is the help
> only, then translating a module will require two steps (one using the
> locale string translation, and another using the .help file).
> If it is for all strings, then does this replace t(), or just augments it?
> Are we confusing people by having more than one interface?

The idea is to not use PO files and t() in the first place for the help text, 
because for larger text strings they're much slower than a simple database 
hit.  

The idea was for modulename.es.help to contain the full translated text.  So 
(using the XML example before) module.help would read:

<drupal:entry key="stuff">And now, open the door.</drupal:entry>

While module.fr.help would read:

<drupal:entry key="stuff">Et maintenant, ouvrez la porte.</drupal:entry>

> Here is a late night thought: Can t() be extended so that if it is
> passed an array, with 'key', then it would lookup a string that has
> the key passed rather than just the string?

I don't know, as I've never used PO files myself. :-)  My only use for 
translation so far personally has been to customize the built-in text for a 
client by creating a fake locale and "translating" just a few strings to have 
more app-specific text.  

Translation people, any thoughts here?

> Something that ties into t() would be great, for the sake of ease of
> use, unification of interface, and not confusing
> developers/documentors...
>
> Regards

-- 
Larry Garfield			AIM: LOLG42
larry at garfieldtech.com		ICQ: 6817012

"If nature has made any one thing less susceptible than all others of 
exclusive property, it is the action of the thinking power called an idea, 
which an individual may exclusively possess as long as he keeps it to 
himself; but the moment it is divulged, it forces itself into the possession 
of every one, and the receiver cannot dispossess himself of it."  -- Thomas 
Jefferson