API page: http://api.drupal.org/api/drupal/includes%21bootstrap.inc/function/t/7
The docs for t() on D6 [http://api.drupal.org/api/drupal/includes!common.inc/function/t/6] have excellent examples of how to correctly use the placeholders in different circumstances:
For example:
$output = t('There are currently %members and %visitors online.', array(
'%members' => format_plural($total_users, '1 user', '@count users'),
'%visitors' => format_plural($guests->count, '1 guest', '@count guests')));There are three styles of placeholders:
!variable, which indicates that the text should be inserted as-is. This is useful for inserting variables into things like e-mail.
[... etc]
These appear to have been lost.
t() now directs the reader to:
a) the Localization API page at http://drupal.org/node/322729, which does not have very detailed examples
b) the format_string() function, which has a very dry summary of placeholders that doesn't explain to the uninitiated what the different types actually do.
I used to be able to direct people on IRC to the docs for t() and all would be well. Today someone has just told me "There's much contention about how to do it and with what function".
Perhaps these comprehensive examples were moved somewhere rather than removed, but I can't find them after specifically looking for them for 5 minutes, so I doubt that someone who doesn't know they exist will be able to stumble upon then.
Please could they be restored to the documentation for t().
Comment | File | Size | Author |
---|---|---|---|
#4 | placeholder_doc-1862198-4.patch | 959 bytes | plopesc |
Comments
Comment #1
jhodgdonThe docs on how to use the placeholders for t() have been moved to the format_string() docs, and the t() docs do say "See format_string() for details" in the appropriate place.
Comment #2
joachim CreditAttribution: joachim commentedYes, that's correct. But that doesn't say to newcomers 'You need to go and read this link to use this properly'. It seems to say, 'There are extra dry details for developers who tinker with the internals over there'. The information that everyday developers need to not use t() incorrectly needs to be on the actual page were it will be seen.
Comment #3
jhodgdonOK, then let's make a small patch to t() that would make it clearer where to find the docs, but let's NOT duplicate the documentation on format_string().
Comment #4
plopescHello.
Attaching patch indicating that the arg handling doc is in format_string() function.
If you consider that the message should be more clearer or explicit, let me know.
Regards.
Comment #5
plopescChanging status
Comment #6
jhodgdonSeems fine to me, thanks!
Comment #7
tim.plunkettRelated #1873608: Improve documentation of format_string() to emphasize that it is used to prepare variables for HTML display
Comment #8
jhodgdonThanks again -- committed to 8.x and 7.x.