Build better tokens with parameters (and use them to replace help text)

Sounds like a smart idea!

+    foreach ($tokens as $name => $original) {
+      $replacements[$original] = url($name);
+    }
+  }
+
+  elseif ($type == 'documentation') {
+    foreach ($tokens as $name => $original) {
+      $replacements[$original] = variable_get('system_external_documentation', 'http://drupal.org/') . $name;
+    }
+  }

Most likely, those need to be check_plain()-ed, right?

Great idea.

How would you treat the difference of e.g. internal help links ... help links to drupal.org manuals ... APIs and even contrib specific sources?
Is your solution only intended to cover drupal.org links?

While i see a good reason to e.g. cover specific documentation on a custom server, i would expect to never see the drupal.org manpages copied/mirrored to a custom location. So if i do mirroring for a specific project, i only want to redirect those links that i mirror.

What kind of separation do you think makes sense (and possibly what kind of extensibility)?

What I can say about this is that this is kinda an abuse of the token system as you wouldn't have any tokens defined in hook_token_info() since it's just [internal:*] and [documentation:*] and there's nothing actually *defined* in the second part of the token - this will break things like token tree display.

From a help-writing perspective, I'm +1 on the concept, as long as Dave Reid is OK with the Token implementation...

Regarding that, the Token implementation seems a little backwards from the rest of the token system. For instance, if you are doing something with a comment and want a token representing the last login date of the user who created the node being commented on, you do something like (I may have the details wrong, but something like this):
[comment:node:author:last-login:short]
This is a chain that progresses from the starting point (the comment) through different pieces of information, with each part of the token supplying its output as the next item's input, and where the items are from different modules' token types. Also, at each point in the chain, as you are building up a token, something like the Rules UI can list for you all possible next items you can put in the chain, because they are each explicitly listed in a hook_token_info() implementation. (For instance, if you have done comment:node, it knows to then give you the node: tokens supplied by various modules.)

It doesn't seem like this proposal will work with either chaining or with the idea of being able to list all available possibilities, in its present form, and given that the current Token system (I think) doesn't support variable next-item-in-chain.

{As a side note, I just filed #1483662: URLs for drupal.org module help pages need updates because I noticed the URLs for help docs are out of date.}

I still just don't really understand what the benefit is here of using tokens compared to the existing method of putting links in with t(). Also the 'url' token type is kind of already reserved by the Token module to move into core: http://drupalcode.org/project/token.git/blob/8f89f245a332ecf69c6d9d77716...

RE [comment:node:author:last-login:short] -- that is what you do when setting up certain Rules in the Rules module... Let's see...
hook_token_info() - this describes the "needs-data" and "type" parts of tokens.

Hm. It doesn't look like the core token_replace() supports this actually... It's possible that this is just something Rules does, and not part of the base Token system, but it seems to key off these needs-data and type parts of tokens from the core system.

Probably Dave Reid would know better than I would. :)

I also think that this is better suited for a filter with using documentation://handbook/... and internal://admin/help rather than using tokens for them. It would be nice if we could run the help text through the filter system rather than tokens.

See also #401956: Provide an [internal] filter

RE #11 -- yes, a filter makes more sense than tokens to me too, since I don't think this fits with the Tokens paradigm. But I also don't see the problem with using t() like we always have, and substituting in URLs. That pattern is all over core, in shorter text pieces, and I don't see why we would want to invent another pattern just for help?

Yeah I don't see why we need to change what we're doing either. I also don't get why you'd want to map *all* d.org links to a different domain either. You'd have to support every single possible link.

If you want to rewrite d.org links, it would be better just to run them through url() so that they could be modified with hook_url_outbound_alter() instead.

5: 1445144_parametrized_token_help_02.patch queued for re-testing.

Thank you for sharing your idea for improving Drupal.

We are working to decide if this proposal meets the Criteria for evaluating proposed changes. There hasn't been any discussion here for over 8 years which suggests that this has either been implemented or there is no community support. Your thoughts on this will allow a decision to be made.

Since we need more information to move forward with this issue, the status is now Postponed (maintainer needs more info). If we don't receive additional information to help with the issue, it may be closed after three months.

Thanks!

Since there's been no follow up going to close this one out, but if still a valid task in D11 we can always re-open

Thanks!