Actions, Stamps and Quickstamps

Recently, in this thread, there was discussion about confusion as to the nuances of actions vs. stamps vs.quickstamps.

I’ve just added this new page to aTbRef and would welcome comment as to omissions/errors. I’m very aware that when writing from a position of prior expertise it’s easy to unwittingly omit things that aren’t obvious until you know.

The new page has—I hope—relevant outbound links but isn’t inwardly linked yet from the rest of aTbRef as this is essentially still a draft.

To assist better quality linking (plus the trend now is back to smaller screens), I try to keep individual articles short and this is probably long enough. So it may be we need to split this article out. However, to do so might undermine the starting premise of comparing actions, stamps and quickstamps.

I think the topic addresses two discrete starting points:

  • “I got an unexpected result”, i.e. which thing does what.
  • “Which is the correct method”. The new user’s problem of an expectation that there is a single/right way to do things. For this group the main point is to show that there are a range of options.

Does the article confuse things a bit with the intro:

image

The intro and list imply that Quickstamps “apply action code to note(s)”. They do not. They merely change values of attributes. I think failure to clarity that important distinction was a part of the confusion that lead to the thread you linked to.

Also

A quickstamp is a fast method to (re-)set the value once for a single attribute for every note currently selected. Unlike a stamp, the code is not saved and cannot act on more than one target attribute at a time. Quickstamps can only be used via the Properties Inspector’s Quickstamp tab.

True, but there’s no “code” involved in a Quickstamp, so there’s obviously nothing to save. I would get rid of the highlighted phrase.

IIRC the Quickstamp input could be an expression although it is most usually a literal. Well, if that was true, it seems so no longer so the point is well made: a quickstamp can apply only literal values to the selected attribute.

I’ll have another stab at the article in due course. In the meantime more critique welcomed.

I know some use Quickstamp a lot. Over the years I’ve found it so confusing (though its UI has improved) that I’ve tended to use some other method. That probably accounts for my blind spot above!

As the initiator of the original thread many thanks for writing up a new page in TbRef. I’m sure will help TB users in the future. The text already addresses the main issues.

Some brief comment:

  • by “container based” in the intro you mean “Containers”, “Agents” and “Map adornments”. Are there any other container types ? If not worth simply listing the exact names of note storage constructs to be complete and precise
  • Adding to Paul Walters comment it is important to point out that QuickStamps unlike stamps only allow setting a single attribute to a specific value (not using expressions or action codes).

For the rest it’s useful to see that certain actions only work once upon add etc… and that sometimes the OnAdd action appears but does nothing e.g. for agents.

Thanks again

Hi @mwra, in addition to the other thanks and suggestions you’ve received here, let me add my thanks as well, and a few additions or suggestions. I think this page is potentially very useful in giving overview clarification of similar-seeming functions that have important nuanced differences. Also it touches on many important points of nuance.

So, main point is thanks for your doing this.

Extra possible points to consider:

  • To avoid possible ambiguity, I suggest that you rephrase one of the early lines, about on-add actions. It now says “This an action applied once to each note… This includes changes that turn notes into containers…” I think the “This includes changes” part could be misread by less experienced users to suggest that you’re talking about the changes that the action code makes in notes.
    I suggest you consider saying instead: “These on-add actions also take effect when the note containing the on-add code is converted into a container: that is, when another note (or notes) is dragged onto it, creating new child notes to which the on-add action will apply.” That is longer but less likely to be misread.

  • In the mention of QuickStamps, how about another line spelling out that a quick stamp, unlike all the other actions described here, will not evaluate expressions. You could say something like: “Please note that a QuickStamp, unlike the other actions described here, is not designed to evaluate expressions. That is, you cannot use a QuickStamp to change the value of $Date to “$Created” or some other attribute value. You would need to enter a literal date, or else use a Stamp or Agent instead.”

  • My policy with QuickStamps is pretty much like yours – I rarely use them – but my experience is that they have some parsing ability. For instance, they’ll convert “today” properly for a date attribute. But if you just point out that they can’t take values from other attributes, that would be useful.

  • You mention this feature: "Agents also have an OnRemove action but note that it is applied to an alias of a note, so pay attention if altering intrinsic attributes."
    If find myself intrigued by the “OnRemove” action for an Agent, rather than a container or an attribute, in this sense. Being matched by an agent is of course a volatile thing, unlike presence in a container or on an attribute. Each cycle, a note matches, or it doesn’t. I’m intrigued that Tinderbox can keep track of whether a note that matched on Cycle #559 no longer matches on cycle #560, and what that means for its continuing not to match on #561 (and the ways that is different from “else” code). Not asking you to spell this out here, but it is logically interesting.

Again, this is very useful, thanks for the whole discussion.

1 Like

Yes I do mean based on items that are ‘contained’ by something else. I’ll add link to a definition of container. I’m deliberately trying not to make every note self-contained as they’d be too long and it completely defeats the purpose of a hypertext resource. By linking, readers can look up terms they don’t yet understand and this avoids clogging the article with parenthetical side explanations.

OK, I’ve updated the article, drawing the distinction between code-based entry and literal values. As can be seen nothing is totally clear-cut, qv the ‘evaluate’ option in KAs and Get Info actually allows use of action code (albeit not stored code - actually even that by evaluation action()!).

Essentially there is now a 3 level hierarchy. If it doesn’t seem simple, it is because it isn’t. There are multiple ways to do things. That’s a structural aspect of Tinderbox, and which repays the user in the long term.

Further critique welcome!

OK, a further revision - probably the last for today - but I wanted to take in @JFallows’ useful observations.

Until testing for this article**, I’d never thought about OnRemove. I’d not consider it something a new user should want to try out first. I think the mechanism is simple. My understanding is that after the first cycle of an agent, it doesn’t throw away existing aliases (efficiency) but re-evaluated in scope notes. It adds aliases for new matches, retains pre-existing match aliases and removes aliases to now non-matching notes. The last provides a perfectly good trigger point for OnRemove to fire. As with an agent’s action (its OnAdd equivalent) the OnRemove evaluates in the context of the alias and not the original.

** After 14+ years of Tinderbox use, I’m still finding things I’d overlooked or forgotten. Writing reference articles does that sort of thing!

New edit is online here.