In particular, please review and confirm the below definition, and that all Tokens are "text" tokens. I removed the word "Text" from "Text Token" because it impiies there is some other type of Token.
Definition
Tokens in Keyboard Maestro represent placeholders for information about a specific object. For example, the %SafariTitle% token returns the title of the current Safari tab. So the value of the Token will be determined at execution time. All tokens return a text value, even if the source data was some other data type.
Looks fine. Yes, text tokens are only text, so the text is redundant if the reader knows what the token is referring to, otherwise it might add clarity. It is also used in the User Manual, and probably a bunch of other places. It’s not inconceivable there could be some other kind of token in the future either.
If you’re looking at the TOC for the User Manual (ie, https://wiki.keyboardmaestro.com/User_Manual), and it just says “Tokens” instead of “Text Tokens”, are people likely to have any clue what that is about? I’m not sure.
If the reader does not know what a Keyboard Maestro "Token" is, then I doubt it would give much clarity by stating "Text Token". To state the obvious, "Text" is an adjective describing "Token". It is only helpful if I already know what a "Token" is.
If I tell you I have a red widget, what do you know? Not much, except it is something red. The fact I stated "red" implies there are likely widgets of other colors.
Seems to me that the first line in the "Tokens" article makes it pretty clear:
Tokens in Keyboard Maestro represent placeholders for information about a specific object.
But then some readers may not know what "placeholder" or "object" means.
That's why I put an example next:
For example, the %SafariTitle% token returns the title of the current Safari tab
At this point most readers should be getting a reasonably clear idea of what Keyboard Maestro Tokens are, and they have had to read only two lines.
You are already using only "Token" in two key places:
On the Action, you say "Insert Token"
The Wiki topic title is "Token"
So, one approach is to just remove "Text" from "Text Token" as we come across it other articles. Of course, you may want to go ahead an change the TOC and Glossary now.
I think it’s good for nomenclature to be consistent, so when you insert a token in an action you’re not obviously inserting a “text token”. I remember being confused by these when I first started looking at them.
I think tokens are very confusing to most users and should be explained more explicitly.
Just throwing out ideas here:
A token is a just a label that represents something else – like:
SafariTitle.
In order for Keyboard Maestro to understand this is more than plain-text and know what to do with it, it is delimited using percent characters.
%SafariTitle%
Now Keyboard Maestro knows to expand this into the title of the front web page in Safari.
Except of course when it is used in a calculation field, in which case you do not use %. (Right?)
I’ve also found tokens confusing. Don’t get me wrong - they’re invaluable. Its just the rules for how they work confuse me. And while I think I understand it now, I’m never sure.
Any suggestions for how to improve the wiki to clarify what is confusing to you?
Chris, this looks pretty explicit to me. How would you improve it?
Tokens in Keyboard Maestro represent placeholders for information about a specific object. For example, the %SafariTitle% token returns the title of the current Safari tab. So the value of the Token will be determined at execution time. All tokens return a text value, even if the source data was some other data type.
So if I understand this correctly, tokens are NOT usable in calculation fields? Perhaps the things I thought were tokens in Calculation fields are actually called functions? Is that correct?
By the way, in one place you say "a Action" instead of "an Action".
Most people don't really understand the concept of delimited text labels. They don't realize that the percentage signs are symbols arbitrarily selected by Peter to represent a token.
Tokens in Keyboard Maestro represent placeholders for information about a specific object. For example, the %SafariTitle% token returns the title of the current Safari tab. So the value of the Token will be determined at execution time. Note that the % symbol is used to identify a token. You normally see this shown as %SafariTitle%
All tokens return a text value, even if the source data was some other data type.
I can't decide whether or not I like the use of the <kbd> symbols in this context, but I'm tired and need to hit the rack soon.
Here's my take pour le moment.
Tokens are a very powerful feature of Keyboard Maestro that permit the rapid acquisition and use of all sorts of information from the System, the Clipboard, the Screen – Dates – Google Chrome, Mail, Safari, iTunes – and more.
A Token in Keyboard Maestro represent a placeholder for information about a specific object. For example the %SafariTitle% token represents the title of the frontmost Safari tab, and the value of the Token will be determined at execution time.
Percent symbols are used to delimit tokens – a few examples follow:
See Menu > Edit > Insert Token for a complete listing of all available tokens.
Tokens always return a text value, even if the source data is some other data type.
I've had experience for years now with users who don't know tokens exist.
Or they knew they existed but had NO idea what they were or how to use them.
Or they had tried to use them and failed.
Or they had tried to use them and succeeded and failed in a confusing manner, because they had no idea of the difference between Keyboard Maestro's different types of fields.
What's a token?
Why should I care?
How is it useful to me?
How do I use it?
We need to answer all those questions and probably more I'm missing.
Usually when I encounter user issues like this, I find a video tutorial is the best answer. I'd be happy to do one, just not sure how to script it - in other words, what should the video show?
I tried to capture a lot of the "how-to" questions with my animated GIF.
Do you guys think it needs to show something differently?
I like videos for longer, more complicated workflows, but prefer animated GIFs for the short and quit demos. The user doesn't have to do anything to view, and doesn't take him/her away from the topic.
Yes, tokens are only used in text fields, and functions are only used in numeric fields.
Except, naturally, the new text functions (like CALCULATE and WORDS) take text which can contain tokens, and text fields can include the %Calculate% token which can contain functions.
As noted, the percent character is used to indicate the presence of a token. Because it is plain text otherwise, there must be some way to indicate when you include the word "Variable" whether you mean just the word Variable or the text token Variable. The percent characters distinguish between the two by signifying the tokens. The generic concept is called a Template, where placeholders are included in text by somehow marking them.
The same sort of technique is not needed in a numeric field because the only conflict is with variable names. Functions (and text operators) use capitalized names to avoid any conflict and ensure they stand out.
Tokens and Functions are also substantially different with little overlap because tokens return textual information and functions (by necessity) return only numeric information. Any function could, in principle, have a token counterpart that returned the same number, so that tokens were a strict superset of functions, but most functions would rarely be used in a text format.
