KM Dicitionary

Questions & Suggestions
1

Quick request/suggestion. At first blush, my post about conditionals, the one I posted yesterday - at first blush - seems microscopic - but I ran into hose issues while creating a macro the day before, that took me longer than I care to admit.

Alongside the manual, wiki and this Forum, it would be nice to have a detailed dictionary that plunges into KM's actions, variables, etc., in an in-depth way. This way, if a macro requires a close look at tokens, variables... whatever, it can be used as a reference. Sorta like an Oxford Keyboard Maestro Dictionary, whenever you need it. I suppose that would be labor intensive.

2

Why doesn't the KM Wiki fulfill that need?

There is a Help item in the Gear menu of every Action that links to the Wiki for details.
Every Edit > Insert > Action or Token or Function can display the help by holding down the OPT key and then clicking on the menu item.

And then there are detailed general subject pages like on Variables , Scripting, Regex, Dates, Macro Activation, General Terms and Definitions, etc.

The KM Wiki is really quite detailed and comprehensive. Of course, there are a few places where it could be improved, and if you find one of those, let us know.

1 Like
3

KM really has a great Help System:

Beyond the things you find in KM Editor’s Help menu (I guess you have explored them), you always have the gear menu on any action. The “Help” menu item in that gear menu takes you directly to the related KM Wiki article.

The Wiki is not perfect and will never be, but it is very good and very comprehensive. And –very important – it is actively developed, i.e., updated.
(Compare this to the“ help” system of many other apps where when you click on the Help of some menu command you get just the literal text of the menu command as response.)

1 Like
4

I'm happy to answer your question but I'd prefer not to dialog about. Kindly respect my wishes. (While I'm sure you can find an exception - so don't bother), nearly every issue discussed in my post, Question About Conditionals, cannot be found in any of the references you mention above.

I realize, you have done writing for Peter but my point remains. But again, I do not want to go into this in any depth because this is a public forum and such a discussion may appear critical of KM.

As Peter knows, after working with a bunch of automation programs over several decades, to my mind, KM is in a league by itself.

However, it needs a dictionary and it needs a skilled writer to write that dictionary. I'm not going to point out places that need improvement - as you requested - for the reasons stated above.

But I'll make a recommendation that responds to your request just as well. Michael: read my post, A Question About Conditionals - and really read it, don't just skim it. You'll find gads of areas that need to be included in such a dictionary.

If I understood everything Peter wrote in his reply to my post - and I believe I do - the term 'While' itself is a misnomer.

That action should not be called 'While'. I would go so far as to say, 'While' is straightout misleading. Read the post with particular attention to Peter's description of the action, 'While.' Read it even though I know how much of an expert you are and that you're sue you understand the actions.

Who knows, you might even learn something. While I would want to give it more thought, off the top, 'When' would be a more accurate name for that action. THat action does not execute actions WHILE specified conditions are presented to it. For a piece of software to be powerful - and I for one believe, KM should have the kind of popularity a Microsoft Word has - the writing needs to be accurate. For someone who well versed in the English language, the name 'While' caused unnecessary confusion.

I can go on and on about areas of KM that cause people confusion. I say this with certainty because every several months I read the same questions and the same confusion. It's not the programming or the software. It's the writing. The writing misleads people.

I would ask that this dialog stop here. Normally, I wouldn't have written this but you asked and so I answered your questions. If you have anything further to tell me, Sheriff, you can do it back channel by writing to Peter and he will communicate whatever you need to say. Thank you.

1 Like
5

The dictionary, such as it is, is in the Glossary section of the user manual section.

If there is items missing, feel free to point them out, then I could add them when I think of it - or not, which is fine.

That may be, but the loop names have been defined for decades.

See Wikipedia, Structured Programming, specifically:

  • "Sequence"; ordered statements or subroutines executed in sequence.
  • "Selection"; one or a number of statements is executed depending on the state of the program. This is usually expressed with keywords such as if..then..else..endif .
  • "Iteration"; a statement or block is executed until the program reaches a certain state, or operations have been applied to every element of a collection. This is usually expressed with keywords such as while , repeat , for or do..until . Often it is recommended that each loop should only have one entry point (and in the original structural programming, also only one exit point, and a few languages enforce this).

As you can see, these are the same elements that Keyboard Maestro uses:

The same elements I used when I programmed Pascal. More or less the same elements used in C and all its derivatives.

I'm afraid if you don't like the terminology you will require a time machine to go back and visit Dijkstra some time in the early 60s, and have a chat with him about his naming choices.

Although in any event, the While loop does what it says: While the condition is true, execute the actions. Now you can nitpick and say, “hang on, if the condition becomes false half way through the execution of the actions, why don't they stop executing”, but that is not how it works - consider both the condition and the actions to be atomic indivisible chunks of code as far as this behaviour is concerned. While the condition is true, execute all of the actions, then check the condition again.

There is no question the documentation could be different, the terminology could be different, the design could be different, etc - but no documentation will satisfy everyone, no terminology will make sense to everyone, no design will be optimal for everyone. That's life, it is full of history and compromises.

In any event, yes, there is a glossary, and if anyone wants to suggest additions, they are free to do so, or not, because no one, other than me, is actually paid to improve Keyboard Maestro, and so no one, other than me, has any obligation to do anything.

I'm happy to lock this topic if it is not going to be constructive.

7 Likes
6

As you know, Peter, "could" does not mean "should". :wink:

To all interested readers:

I have worked with many, many apps, tools, and systems for over 3 decades, and I can say without hesitation that the KM Wiki is the best, most thorough documentation I have come across.

Could it be better? Of course. A wiki, by definition, is a live document, and we have been continually improving it for years. The best thing anyone can do who finds it lacking is to point out the specific page/section on the Wiki that they find needs improvement, and, even better, then to suggest how to improve it. AFAIK, we have always responded to such requests.

2 Likes
7

Consider this loop:

While the red cockpit light is lit,
Drop bombs

If the light goes off immediately after the first bomb is dropped, that bomb will still fall. The change in condition does not eliminate gravity. Yet, I don't know of any word better than "while" to describe the execution of the instruction, and even if a better word exists, it certainly is not "when", because "when" does not imply "continue to".

3 Likes