I expect that this idea would be of limited appeal and therefore not worth the implementation effort but it is not for me to assess that, so…
One of the “engroup” options that can be applied to one or more selected actions is “macro”. The selected actions are removed from their macro to a new macro, and their place is taken by an execute macro action that executes the new macro.
The new macro is named the same as the first macro, but with “Subroutine” appended. For example, macros that are “engrouped” from a macro called:
Do something very complicated and log the results to a global variable
would appear in a macro called:
Do something very complicated and log the results to a global variable Subroutine
(even though they are replaced with an execute a macro action and not an execute a subroutine action!).
I frequently use engroup > group on actions to organise them into units within macros. It would be useful if, when engroup > macro is applied to a group, the new macro were named the same as that group.
For example, actions that are in a group called Do something quite simple would end up in a new macro called Do something quite simple. It seems to me that that would be logical and convenient. It might however be said that this suggestion gives special treatment to the group action above other actions.
It would also be handy if dragging such a group to the “Macros” column moved the group out into a new macro (as an alternative to the existing engroup mechanism).
Perhaps the suggested behaviour should be expanded to using group > macro on any actions. The behaviour would then be in line with what happens when one copies actions into a new, unnamed macro: the editor names the macro after the first action.
I can't see doing that, it's too much of a special case.
Yes, probably there should be two options in the menu, one for Subroutine and one for Submacro.
It's an interesting idea, although it's a little odd, since it would be neither a move nor a copy, which is what a drag would normally be. And if I did the above, then there would be the question of which to do for this.
Sure, although as I mentioned afterwards, it need not be.
That would be useful.
The capital “S” in “Submacro” there makes me wonder if you might be minded to use “Submacro” as the label for the option. May I suggest that “macro” would be a better choice there?
I would take “submacro” as an informal (not officially defined for KM) term for a macro that happens to be the target of an Execute a macro action—in which case, a "submacro" really refers not to something that is different from a macro but rather to a macro that just happens to be the target of an Execute a macro action. There would be no benefit in the UI implying that "submacros” are distinct from “macros".
Of course, subroutines are really only macros for which a user has added a subroutine trigger, so again it depends on triggering methods, but here the trigger unlocks extra capabilities for the macro. The extra terminology is therefore justified (albeit at the risk of giving the impression that a subroutine is an inherently different entity from a macro).
While on the subject: I still feel that, for clarity, the wiki should avoid using phrases that maybe be misinterpreted as official (defined) terms.
The wiki defines a subroutine as “a sequence of actions that perform some sort of sub-task”. That fails to indicate that subroutines are just (trigger-enhanced) macros, and it introduces the term “sub-task”, which the reader might well understand to be more jargon to be understood, rather than a figure of speech.
Similarly, the Execute a Macro page introduces the term “sub-macro” unnecessarily (that page is, as I have previously suggested, a tough read, and I notice now that it tells us that the action cannot be used to pass parameters, before telling us how it can —so no, that page is not me favourite[1]).
More properly -- any macro that is executed via the "Execute a Subroutine" action (which, implicitly, requires it to have a subroutine trigger).
That's because a "subroutine" macro can also have other triggers, allowing it to run "normally" -- but when called via the "Execute a Subroutine" action it gets subroutine behaviour such as proper parameters, a returned result, and forced synchronous execution (perhaps the reason for the term "sub-task").
The Execute a subroutine action’s dropdown menu shows only macros that have been assigned a subroutine trigger. The presence of the trigger is the only criterion for being in that list of subroutines.
A subroutine macro that is never executed via that trigger still remains in the list, obviously.
There is no indication in the UI that a macro with a subroutine trigger is not fully blessed as a subroutine until it has been executed[1].
I read “sub-task” (as used in the Subroutines page) as referring simply to a task that is to be broken into smaller tasks. I am glad that your reading is different; it helps confirm my point that undefined terms in the documentation are better avoided!
I don't think so, because the first two points (I'm not sure what you mean by the third) necessitate the "Execute a Subroutine" action. It's the combination of the "Execute a Subroutine" action triggering a macro with a "Subroutine" trigger that executes a subroutine instance.
...it is just another macro. It can only take one parameter, it can't return a result, but it can be executed asynchronously.
But when executed via:
...it's a capital-S Subroutine!
In practical terms it doesn't make much difference. But it makes documentation tricky, especially when Subroutines page discusses subroutines as general theory, old-style "Execute a Macro" subroutines, and macros with v10+ Subroutine triggers, all in five short paragraphs...
In terms of an instance, yes. In terms of a Macro, no. Previously you referred to macros, not to an instance of a macro.
More properly -- any macro that is executed via the "Execute a Subroutine" action
Now that you have used the term “instance”, I understand why you emphasise execution in your definition!
However, I do think it important to explicitly distinguish between macros and instances of that macro.
To recap, that unclear third point was:
If a macro with a subroutine trigger appears in the list of subroutines, the UI is confirming that it is indeed a subroutine. It does not matter whether that macro has been executed or not, in terms of the macro.
Certainly the instance that is generated by an action is not a subroutineinstance of the macro-with-a-subroutine trigger, but in terms of the macro, and, again, backed up by what happens in the UI, I believe it is correct to say that:
A macro-with-a-subroutine-trigger can always be passed multiple parameters, and it can always return a result. The fact that it does not in that example does not mean that the macro-with-a-subroutine-trigger is not a subroutine; it means only that it is not being called as one. In other words, the extra capabilities that the trigger has bestowed upon it are not being utilised by execute a macro in your example.
But when talking of instances of a macro, you are quite correct in saying:
Another way to look at the issue would be to ask whether a KM subroutine is—in terms beyond those of KM–a “subroutine”. The answer would be that subroutines are not always “subroutines”:
The Wiki says that a KM subroutine is (my emphasis):
a sequence of actions that perform some sort of sub-task, and that can be executed from multiple different macros that each require the facility.
I have already made the point that the page should explicitly tie in subroutines with macros, but what it is defining (too loosely) is a macro-that-has-been-assigned-a-subroutine-trigger subroutine, not a “subroutine” as commonly understood in general computing terms—that would, in KM terms, be an instance of a subroutine that is being executed by an execute a subroutine action.
And this is where we disagree. I'd say that a macro-with-a-Subroutine-trigger can only be passed multiple parameters and return a result when being called via "Execute a Subroutine".
The new-from-v10 capital-S Subroutines, as in paras 4 & 5
...and, unfortunately, differentiating v3 by using a capital-S breaks a soon as v1 or v2 get sentence-cased, as above...
So I don't know how to reliably indicate which is meant -- and we have a similar problem with
A subroutine is a sequence of actions that perform some sort of sub-task
...where I automatically take "actions" to mean "KM Actions", for no other reason than "because"...
It's difficult to be both precise and concise, especially when the ideal words have already been used elsewhere, and "macro-with-a-subroutine-trigger called by an 'Execute a Subroutine' action" is going to get old very quickly.
Perhaps the best thing to do is subhead the Wiki page to make it clear that paras 1 & 2 are general info, 3 is old-stylee, 4 & 5 are about the new-ish Subroutine functionality. And the text could be expanded to make it clear that the old-stylee can be run synchronously or asynchronously, but the newer Subroutines are synchronous only.
We don’t disagree. It’s a matter of semantics again (which is the whole issue, of course!).
When I say:
A macro-with-a-subroutine-trigger can always be passed multiple parameters, and it can always return a result.
In itself, it really can. It just does not, unless correctly upon to do so (yes, by an execute a subroutine action).
That is obviously correct. That is not a contradiction of what I wrote.
Indeed. I have tried to be consistent in this topic by indicating KM entities in italics, but as far as the Wiki is concerned, I have maintained that a (KM, remember!) subroutine should be explained in terms of it being a (KM!) macro. Whatever its faults, the page is does not attempt to explain (yes, KM!) subroutines in terms of the computing world beyond Keyboard Maestro, and I believe that is wise. KM is not aimed (solely) at expert programmers and, in any case, terminology can vary across programming languages.[1]
Therefore the page should not use the word “subroutine” as a reference to anything other than to [KM! KM! ] subroutines—and I don’t think it does.
... take off and nuke the entire page from orbit?
I would expect them to be a definition of subroutine (but perhaps that is what you meant).
It’s a historical note that will be no more than a distraction for most readers. It belongs at the bottom of the page, in small text. Small grey text.
But I think I'm being too picky. I'd like a Subroutine to be a macro when called via the "Execute a Subroutine" action, to differentiate from its triggering in any other way and because it's the calling method that makes it "special". But what the hell do you call it the rest of the time?
Conversely, almost any macro could be considered "a sequence of actions that perform some sort of sub-task" and can be called by any other macro -- does that make them all subroutines?
I'm going back to calling anything with a Subroutine trigger a subroutine, and any other macro called from within a macro will be a sub-macro, and I shall hand-wave about the differences and where the edges might be.
And that is why I don't write documentation!
Thanks, @kevinb -- that's opened my eyes to a couple of things, and maybe a trick or two that'll come in handy later...
If you like. Whatever mental model works. But those “subroutines” will not, of course, all be subroutines...
Quite right too. Well, a subroutine.
I think that is in line with how Peter uses the term in the wiki. It just isn’t defined terminology, so, in the wiki, it is a term that I would like to see appear with, say, a discreet explanatory footnote.
Thank you too, and I look forward to hearing about the results of those fancy tricks!
—so no, that page is not me favourite
It always helps to be on the same page, and to have a page that helps us be so!
] subroutines—and I don’t think it does.
