user documentation does not explain "just" target modifier

[jmegner]

I still don't know what "just" does. The doc mentions it but does not explain it. At first I thought that it shrank a target to exclude the selection-type separator (space for token, \n for line, etc), but I am beginning to think that it does more than that.

The doc mentions "take every instance just air" does something very different than what I described above, so apparently I don't understand the "just" modifier in full generality.

[jmegner]

I think this issue and #1522 are perhaps more important than they first appear.

Awhile ago, I asked how to do something in cursorless, and the answer involved "before, "start of", and "just". That was the moment where I most felt that I did not understand the underlying structure of cursorless. And now I notice that none of those modifiers are really documented. They are important modifiers that are useful to doing very common editing operations.

[pokey]

Yeah we should really have more on "just". I believe there's a Cursorless kata about it that's prob the best place to learn about it for now

[jmegner]

What is the best way to show a little bit more on the cheatsheet? Edit

cursorless/cursorless-talon/src/cheatsheet/sections/modifiers.py

Line 48 in a8ea10d

"toRawSelection": "No inference",

?

I think there is a big difference in impact between an explanation in the official doc and cheatsheet vs buried in a 3rd party readme. I still haven't looked at more than a handful of katas. I am willing to work on just doc but will probably need correction.

[pokey]

Essentially the "just" modifier strips the target of any semantic information, treating it as just a dumb range. So eg

• it won't have any delimiters, and
• it also will inherit insertion delimiters from its source in the case of a bring. Eg the difference between "bring arg air and bat after just left paren" and "bring arg air and bat after token left paren" will tell Cursorless to use , as the delimiter when joining air and bat instead of using the token delimiters that"token left paren" would have.
• It's also common to use "just" to break inference chains, because it's a short word that doesn't do too much.
• In the case of "instance", by default "every instance air" will only consider instances of the air token that are themselves full tokens, but "every instance just air" doesn't have such a restriction, because we've stripped air of its semantic "token-ness".

(copied from #1538 (comment))