It's not clear that you have to look at format_string() to find details of t() arg handling

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