Add terse mode

[pokey]

The problem

• When starting with knausj, you begin with a command set that has many different ways to say a single command, many of which are quite verbose, eg
  • https://github.com/knausj85/knausj_talon/blob/7cf33e29d086b6208ba222a1c8727d830ee579e0/core/keys/keys.py#L200-L204
  • https://github.com/knausj85/knausj_talon/blob/7cf33e29d086b6208ba222a1c8727d830ee579e0/plugin/symbols/symbols.talon#L15
• Cursorless supports paired delimiters (eg "round") as part of its target grammar but these spoken forms can't be used for insertion unless people steal it from someone else's grammar or write them themselves
• There is a cliff when people go from being a beginner to being more advanced where they need to construct (or copy) their own terse command set to code efficiently, and then retrain their muscle memory to use this command set
  • There is no recommended terse command set, so people are kind of on their own here

The solution

We propose the following:

• Introduce a tag user.terse_mode
• Place a subset of knausj commands (see eg examples above) behind a not tag: user.terse_mode context
• Create a replacement set of the given commands placed behind a tag: user.terse_mode context
• Add a commented out line to settings.talon to show users how to enable terse mode tag
• Note that some of these spoken forms will require us to change them to an action / capture / list (eg the pair captures above "inside parens"). I believe the issue for that one is https://github.com/knausj85/knausj_talon/issues/546

Alternative solutions

• We could just change the default knausj spoken forms, but that would require us to use the deprecation mechanism, and we may not want all users to have to use the more terse grammar
• We could have a separate repository with these spoken forms, and then just have the tag in knausj only disable the knausj default verbose spoken forms without replacing them, and then have the separate repo enable this tag
• We could add these terse spoken forms to Cursorless

[knausj85]

I'd be more tempted to redesign the grammar from the ground up based on current best practices and improved compatibility/consistency with key things like cursorless.

.talon-lists together with .talon and will make it much easier for folks to customize.

Perhaps it's also time to get serious about versioning to move the needle forward.

[bjaspan]

I initiated the (most recent iteration of the) discussion that led to this PR. I'm still quite new here and I know that I do not yet have a good intuition for how things do or should work, so I do not have high confidence in my opinions.

That said, the primary point I was trying to make is that it would be great if we could figure out a consistent recommended set of spoken forms, particularly for the most common things for coding (like delimiters) so that we can document a straightforward onboarding path for new coding users. The goal would be not to encourage users to learn something that they will have to change later as they get more proficient; we should require them to learn the minimum necessary to get started, but everything they learn they should be able to keep and build on as they gain experience.

My initial reaction to terse_mode is that it is the opposite of that. Unless we tell people to enable terse_mode as soon as they start, they would be learning the non terse way to say things and then have to relearn the terse way later. If we do tell people to enable terse_mode when they start, then we are bifurcating the recommended spoken forms for Talon users; all docs, blog posts, videos, etc. will have to pick one and be incomprehensible to people using the other, etc.

So, +1 to @knausj85's comment to rethink from scratch.

[rntz]

Ideally I think we want a way to evolve our command grammar that is:

1. default for new users
2. opt-in for existing users, so that they don't get commands changed out under them
3. reasonably granular, so old users can opt-in to some grammar changes without committing to everything
4. backward compatible - ideally requiring no change management in Python files at all

[pokey]

@rntz I agree with all of your points. In terms of implementation, how do we go about distinguishing new from existing users?

Fwiw we recently had to solve the problem of distinguishing new from existing users for the Cursorless VSCode extension, in order to show release notes to existing users, but not new users. The way we did that was to push a version of the extension that leaves a value in their VSCode key-value store, tracking the current installed version, and then indicating to VSCode that it should sync this value with the cloud if they have that enabled. We then waited a week, and anyone who didn't have that setting at that point was treated as a new user, so didn't get the release notes shown.

Dropping a piece of state somewhere (like we did above) is one way to do it, but keep in mind that can break if they then go install on a new computer if that state isn't somehow synced. We've had users get confused by that sort of situation in their cursorless-talon files, which don't have any kind of syncing mechanism. Specifically, when the user first installs cursorless, we "eject" the default spoken forms at that moment into csvs (which is one version of dropping state somewhere). That way if we update default spoken forms, they'll still keep their existing ones. I believe there's a similar mechanism in knausj. The problem is that if they then later install on a new machine, after we've changed default spoken forms, they'll get those new ones, and be confused as to why the spoken forms have changed

We could drop the state somewhere in their clone of community so that there's a chance they'll check it in and get it again when they clone on a new computer, but not sure how much we can rely on that

I'm not sure we can solve every problem here; we might have to accept that things may break down slightly if they're running on two computers, and just at least have an easy way for them to patch things up if so (eg an easy way to migrate the state from one computer to another)

[pokey]

Ok so it sounds like everyone here is pushing for the terser command set to be the default. I think that makes sense. Couldn't we just deprecate the existing verbose commands using our deprecation mechanism, and just add the new ones? I also don't think this all needs to happen in one go. We could go piece-by-piece

[knausj85]

My only concern with just adding a bunch of new commands + deprecation is that would probably increase command recognition rates for newbs and they could run away.

Alternatively, we could pursue a strategy such as:

• migrate as much of the grammar to .talon-list as possible first. This greatly eases customization and seems like a solid first step
• develop terse branch, which really should consist almost entirely of .talon and .talon-list changes
• schedule deprecation of non-terse branch

[pokey]

That seems reasonable to me