intro doc WIP with some concepts and a few example walk throughs #1538

jmegner · 2023-06-18T04:06:18Z

I'll put in a lot more links once we start firming up the content. Feel free to suggest big changes.

pokey

This is a nice start! I left some comments inline

pokey · 2023-06-18T13:31:26Z

docs/user/intro.md

+Commands have an action and a target or two. `"chuck air"` has the action `"chuck"` and one target (the `"air"` token).
+`"bring air to bat"` has the action `"bring"` and two targets (the `"air"` and `"bat"` tokens).


Where is the user supposed to be in there user journey when they arrive here? If this is supposed to be one of the first things they see, then they almost certainly won't know what "the "air" token" means

Excellent question. From our group talk, I think we all agreed on this being a Part 2 of a three part series.

Basic. Try to get people to understand "take air", "chuck row 33" and probably highlight the most useful actions.

THIS DOC, intermediate. Getting people beyond the very basics, to start using chained modifiers and understanding the underlying structure of cursorless. Highlight the most useful modifiers and combinations of concepts.

Advanced. At the least, will include: snippets, pairs (if I didn't cover them in part 2), every, instance, just.

pokey · 2023-06-18T13:33:21Z

docs/user/intro.md

+A target can even be a vertical slice or list, like the list `"air and bat"`.
+Doing `"take air and bat"` will result in multiple selections and multiple cursors, but it is still one target.
+
+Commands with two targets often require a separator word between the two targets, like the `"to"` in `"move air to bat"`.


It's not entirely accurate to call "to" a separator word. It actually turns "bat" into a destination. The "move" action expects a destination for its second argument. The words "to", "after", and "before" are the three ways to turn a target into a destination

I will work on how best to introduce the concept of destination. Thanks.

pokey · 2023-06-18T13:33:41Z

docs/user/intro.md

+Commands with two targets often require a separator word between the two targets, like the `"to"` in `"move air to bat"`.
+The separator may seem trivial now, but it is easier to forget it when you start using fancy targets.
+
+### Targets Can Be Modified


nitpicking here, but I prefer just capitalizing the first word of section headings

Sure, I can play nice with that.

pokey · 2023-06-18T13:34:46Z

docs/user/intro.md

+
+### Targets Can Be Modified
+
+A target starts as a mark (`"this"`, `"row ten"`, `"green curve air"`, etc) and target modifiers can be applied to suit your needs.


"starts" is a bit confusing here. It's true that the pipeline logically emanates from a mark, but it is actually the last word you'll say when naming a target

I'll make it more clear. Perhaps: "A target contains a mark and target modifiers can be prefixed to suit your needs."

docs/user/intro.md

pokey · 2023-06-18T13:55:43Z

docs/user/intro.md

+`"chuck just bat"` will not delete any spaces; the `"just"` causes the command to ignore delimiters.
+`"take just just just bat"` does the same as `"take bat"`.
+
+Special positional target modifiers `"before"` and `"after"` try to work with delimiters.


as mentioned elsewhere, I'm hesitant to add more of the old language around "positional target modifiers". These are required words to form a destination

I'll have to rewrite this once I write up the earlier stuff about destinations.

pokey · 2023-06-18T13:56:44Z

docs/user/intro.md

+Special positional target modifiers `"start of"` and `"end of"` do not use delimiters.
+`"bring line to end of row ten"` will bring a copy of the current line content _without line delimiter_ to the end of line 10, meaning line 10 will get content added to it.


i'm not sure how important this is to learn at the start. and you'd likely be better served saying "bring line after last token row ten" anyway so that you get a space

I don't think it is much extra mental burden to know that "before" and "after" have counterparts that don't use delimiters. I think this is the best time to introduce it. I wouldn't get too focused on the practicality of that exact example. I have asked for slack-help on how to do something and got answers with "start of". Maybe was a quirk of how I learned things, but things really clicked when I learned about all four positional "modifiers"; it felt like a small thing with a big impact.

pokey · 2023-06-18T13:57:51Z

docs/user/intro.md

+  - `"bring T1 [to T2]"`: replace selection/T2 with T
+  - `"move T1 [to T2]"`
+  - `"chuck T"`: delete T
+  - `"change T"`: delete T and set cursor(s) to where T was


given all the discussion of delimiters above, it might be worth indicating here or somewhere that "change" doesn't remove delimiters

Hmmm, maybe it is chuck that should be changed to say that it will delete appropriate delimiters as well.

pokey · 2023-06-18T13:58:32Z

docs/user/intro.md

+  - `"drink/pour T"`: edit new line before/after T
+- Selection Manipulation
+  - `"take T"`: set selection
+  - `"give T"`: deselect


I wonder how common this one is

give? Not that common, I guess. I think it originally got into my notes because it felt important at the time. Sometimes I wanted to not have a selection because of its interactions with search stuff. BUT, give this doesn't even work for that. I now use "pre this" or something like "go left". I think I'll delete give from the list.

pokey · 2023-06-18T13:58:55Z

docs/user/intro.md

+  - `"give T"`: deselect
+  - `"pre/post T"`: set selection before/after T
+- Clipboard
+  - `"paste to T"`


do we want to include "paste before" / "paste after"?

Yes! I even want to add it to the cheatsheet.

Co-authored-by: Pokey Rule <[email protected]>

pokey · 2023-06-21T11:59:40Z

docs/user/intro.md

-The big difference between a simple command `"bring air to bat"` and the intimidating `"bring next three tokens air to after just line bat"` is the addition of target modifiers.
-Target modifiers are often chained. `"after just line"` is a chain of three modifiers and they are applied in reverse order (`"line"`, then `"just"`, then `"after"`).
+The biggest difference between the simple `"bring air to bat"` and the intimidating `"bring next three lines air to tail block bat"` is the addition of target modifiers.
+Target modifiers are often chained. `"tail block"` is a chain of two modifiers and they are applied in reverse order (`"block"`, then `"tail"`).


"tail block" is actually a single modifier 😅. It extends its input past the end of its containing block

If you're looking for an intimidating command with a big fancy chain, maybe grab one from one of my videos? eg https://youtu.be/xtOkYdwUves ("move line every instance square plex after file"). Tho keep in mind in that example the second target (the destination "after file") doesn't actually have an explicit mark; it's using the implicit "just this" mark

But the source does break down as a nice long chain. Reading from right to left, it's:

plex

square ("box" in default parlance)

every instance

line

I was hoping to have an example that would be fully explained by the current document; "every instance" is going to be in the next document. I can just change to "block func".

pokey · 2023-06-21T12:00:17Z

docs/user/intro.md

+Target modifiers are often chained. `"tail block"` is a chain of two modifiers and they are applied in reverse order (`"block"`, then `"tail"`).
+
+Modifier chains can be applied to each [primitive target](README.md#primitive-targets) in a [compound target](README.md#compound-targets).
+For instance, `"take tail line air and head block bat"` has chain `"tail line"` applied to `"air"` and chain `"head block"` applied to `"bat"`.


as above, neither of these are really "chains": they're each a single modifier

pokey · 2023-06-21T12:04:52Z

docs/user/intro.md

+Targets are converted into destinations using a destination converter (`"to"`, `"before"`, `"after"`); that is why you have to say commands like `"bring air to bat"` or `"bring air before bat"`.
+The `"to"` might seem like cursorless is trying to resemble a sentence, but `"to"` actually serves a technical purpose of explicitly converting to a destination.
+
+Your destinations should start with a single destination converter before you add modifiers and/or a mark.


would be worth having examples for "paste" / maybe "snippet"

pokey · 2023-06-21T12:05:20Z

docs/user/intro.md


-### Targets Sometimes Include Their Delimiter Depending On The Action And Modifiers
+Commands like `"paste"`, `"bring"`, and `"move"` have a target that is a destination.


prob worth pointing out htat for bring and move the second arg is destination: first is regular target

pokey · 2023-07-09T16:00:02Z

just wanted to check that this isn't blocked on anything from me?

Co-authored-by: Pokey Rule <[email protected]>

…into jmegner-intro

jmegner · 2023-07-24T18:56:41Z

I feel like I should have had more examples, but some of them should go in the advanced guide and this should be a good enough start anyway.

Feel free to choose a better filename. guide-intermediate.md?

jmegner · 2023-08-07T20:19:21Z

Some notes from talking with @josharian ...

Agreed and fairly straightforward:

move useful actions/modifiers sections to top (and change intro a bit).
terser section titles even if less precise.
Some of the simple-when-you-see-it should have example before the technical explanation (chained modifiers, destination converters come before target modifiers).
fix "character or word" vs "argument and item".
some action reordering; select a manipulation first; chuck and change first in changers list
drink/pour are not just for lines (like args)
add IDE action category (like follow)
remove 'n scopes backwards' modifier

Jacob will think about:

Where to add/promote examples that have their own code block rather than an inline before-vs-after.

Controversy!

suggested new section for intersection of destination & delimiter (not sure I understood)
A lot of tweaking can be done for the top-level examples section. We concentrated on the other top level sections.
Whether to distinguish marks vs targets.
How to explain syntactic scopes.

Stuff to remember for when we have more than one guide doc

mention fewer useful modifiers
move join & split examples out, especially to future docs where we talk more about customization
"bring air to its arg" does "f(g(a), b)" => "f(a, b)"; the its makes it out of scope for this doc
it would be nice to have some extra support for before-vs-after examples, like a good way to show cursors, selections, and hats. Someone would have to wizard something up, which means it won't happen soon. Maybe it would be worthwhile to come up with some plaintext conventions like ^angry| a^pple to show hat assignment and cursor position, but I doubt it.

jmegner · 2023-08-10T19:17:41Z

@pokey I think it is ready for you to look again.

pokey

Did a quick pass through the first quarter of this doc. Some great stuff here; left a bunch of minor comments

pokey · 2023-08-13T20:42:19Z

docs/user/guide-intermediate.md

+
+This document will try to:
+
+- Highlight the most useful actions and modifiers in Cursorless so you know which ones to focus on learning first.


If intermediate, then not sure "learning first" is the right term?

To me, "getting to beginner level in cursorless" is pretty shallow. It's understanding hats, this, and a few commands. You don't know all the commands nor do you know which ones are important. Intermediate users at least roughly know which commands they should know. That is actually significant knowledge. You might be surprised how long people limp along with a very small number of commands while knowing they should learn more.

pokey · 2023-08-13T20:42:34Z

docs/user/guide-intermediate.md

+
+- Highlight the most useful actions and modifiers in Cursorless so you know which ones to focus on learning first.
+- Bring together a few important concepts that underlie a lot of Cursorless behavior.
+- Walk through some example editing operations that are common but perhaps tricky to a beginner.


If intermediate, should we use "beginner" here?

The examples are tricky to a beginner who hasn't internalized the stuff in this doc. They won't be nearly so tricky once you are fully intermediate.

Partially based on Jan Wessling saying that the doc comes across as not for beginners...

Highlight the actions and modifiers in Cursorless that the pros use most

That makes it sound like the guide is not for people who are currently beginners. "Highlight the most useful actions and modifiers in Cursorless so you know which ones to focus on learning first" is our intent.

Starting to feel comfortable with the basics?

I would say this guide is not for people who would described themselves as feeling comfortable, even if it is qualified "with the basics".

How about "Do you understand the very basics of how say a command that uses a hat?" instead.

Let's change title to "Getting comfortable with Cursorless" and make no mention of the word "intermediate" unless we are explicitly saying the guide is to help beginners get to intermediate.

pokey · 2023-08-13T20:45:06Z

docs/user/guide-intermediate.md

+  - `"take T"`: set selection.
+  - `"pre/post T"`: set selection before/after T.
+- Clipboard
+  - `"paste to/before/after T"`.


maybe separate this one into "paste to" vs "paste before/after", as you've done with "bring", and add the same note about inserting delimiters?

Ah, right; this used to be below bring, so I didn't bother. I will give it the "bring" treatment.

docs/user/guide-intermediate.md

pokey · 2023-08-13T20:46:40Z

docs/user/guide-intermediate.md

+  - `"bring T1 to T2"`: replace T2 with T.
+  - `"bring T1 before/after T2"`: insert a copy of T1 before/after T2, including appropriate delimiters.
+  - `"move T1 [to/before/after T2]"`: like `"bring"`, but moves instead of copies.
+  - `"chuck T"`: delete T and appropriate delimiter.


do we want to link from "appropriate delimiter" to a deeper discussion with examples?

Ok, I will link to the "Delimiters" section.

pokey · 2023-08-13T20:53:27Z

docs/user/guide-intermediate.md

+  - `"arg"` and `"item"`: often used to involve commas, like `"chuck item air"` or `"bring air after arg bat"` that take care of commas.
+  - `"funk"` for function.
+  - `"state"` for statement (which might span multiple lines or only part of a line).
+- Other modifiers that are like syntactic scopes in that they expand the target.


Suggested change

- Other modifiers that are like syntactic scopes in that they expand the target.

pokey · 2023-08-13T20:55:13Z

docs/user/guide-intermediate.md

+- `"[number] [scope]s"`, like `"chuck three lines row 12"` to delete rows 12-14.
+- `"[number] [scope]s backward"`, like `"chuck three lines backward row 12"` to delete rows 10-12.


I would lean towards using "air" instead of "row 12" here, per discussion on Discord, but not opposed to keeping this to give some variety.

I will change "chuck three lines row 12" to "chuck three lines air" to demonstrate you do not have to supply a line oriented target to n lines.

docs/user/guide-intermediate.md

pokey · 2023-08-13T20:59:13Z

docs/user/guide-intermediate.md

+### Command structure
+
+Commands have an action and a target or two. `"chuck air"` has the action `"chuck"` and one target (the `"air"` token).
+`"bring air to bat"` has the action `"bring"` and two targets (the `"air"` and `"bat"` tokens).


In this case "bring" actually accepts a target and a destination. "to bat" is a destination. Not sure if it's better to be slightly wrong here tho

I thought destinations were a special kind of target.

That's not how we're viewing them today, but I wouldn't say that's wildly inaccurate, and I won't rule out the possibility we'll view them that way at some point in the future 😅. @AndreasArvidsson any opinion on this one?

Since a destination is only a wrapper around the target it's not that inaccurate.
air = target
to = insertion mode
to air = destination

I have definitely referred to destinations as targets sometimes. That said I'm not sure if it's a good habit or not :D

pokey · 2023-08-13T21:00:41Z

docs/user/guide-intermediate.md

+
+A target can be more than a single token or line. A target can be a [range](README.md#range-targets), like `"air past bat"` that spans from the `"air"` token to the `"bat"` token, and that is still considered _one_ target.
+A target can even be a vertical slice or list, like the list `"air and bat"`.
+Doing `"take air and bat"` will result in multiple selections and multiple cursors, but it is still one target.


I do wonder how important this distinction is. We're actually not even consistent on this point internally. When the command comes from Talon to VSCode, it comes across as a single logical target, but after running our target pipeline, we call each output a target

These statements were helpful to my understanding when I internalized them. It also helps when reading the reference or talking to other people.

Co-authored-by: Pokey Rule <[email protected]>

pokey · 2023-08-30T14:40:37Z

docs/user/guide-intermediate.md

+
+- Words in square braces (`[]`) are optional, eg `hello [world]` means you can say `"hello"` or `"hello world"`.
+- Slashes (`/`) show alternatives. For example, `hello/world` means you can say `"hello"` or `"world"`.
+- Targets are represented by `T` with a possible digit, eg `T` or `T1` or `T2`. For example, `bring T1 to T2` means you can say `"bring air to bat"`.


Do we want to include examples in this section? I like the idea of being example-heavy

Examples of what?

If you mean examples of the [T/T1/T2] syntax, what you have seems good.

fixed bug

jmegner · 2023-12-24T17:45:43Z

I'm semi-back from other stuff. I think you last mentioned about breaking the PR into smaller chunks, and it makes sense for the author to do it as they work, but since I am no longer adding stuff, you have all the info I have for however you want to merge it in. I don't know what chunking you would find most helpful.

jmegner · 2024-02-23T17:25:03Z

Guide ported to https://github.com/jmegner/cursorless-unofficial-doc/blob/main/README.md

pokey · 2024-06-20T10:14:54Z

Shall we close this now that it has its own home? We can start to integrate pieces of your guide into the official docs as we move forward

jmegner · 2024-06-20T21:19:01Z

Sounds good to me.

intro doc first draft with some concepts and no example walk throughs

606534d

jmegner changed the title ~~intro doc first draft with some concepts and no example walk throughs~~ intro doc WIP with some concepts and no example walk throughs Jun 18, 2023

pokey reviewed Jun 18, 2023

View reviewed changes

pokey mentioned this pull request Jun 18, 2023

user documentation does not explain "just" target modifier #1537

Closed

jmegner and others added 3 commits June 18, 2023 22:27

pokey suggestion for intro.md

0bdd1a7

Co-authored-by: Pokey Rule <[email protected]>

intro.md, remove "to" from "to after"

a1ba7df

Co-authored-by: Pokey Rule <[email protected]>

refine concept sections

b31db45

pokey reviewed Jun 21, 2023

View reviewed changes

some line examples

2a0950c

jmegner changed the title ~~intro doc WIP with some concepts and no example walk throughs~~ intro doc WIP with some concepts and a few example walk throughs Jun 23, 2023

Jacob Egner and others added 7 commits July 24, 2023 11:31

add more examples and highlight of more useful modifiers

8eafc23

intro doc first draft with some concepts and no example walk throughs

26070d7

pokey suggestion for intro.md

368733b

Co-authored-by: Pokey Rule <[email protected]>

intro.md, remove "to" from "to after"

39efd7e

Co-authored-by: Pokey Rule <[email protected]>

refine concept sections

66aa3a3

some line examples

3380085

add more examples and highlight of more useful modifiers

bc84f35

jmegner force-pushed the jmegner-intro branch from 8eafc23 to bc84f35 Compare July 24, 2023 17:55

Jacob Egner added 2 commits July 24, 2023 12:57

Merge branch 'jmegner-intro' of https://github.com/jmegner/cursorless …

568f56f

…into jmegner-intro

act on some pokey suggestions

95e6616

Jacob Egner added 3 commits July 29, 2023 09:31

add pokey's "break" command to "split lines" example

4802c11

change intro.md to guide-intermediate.md

369430d

typo fixes

076a833

josharian mentioned this pull request Aug 7, 2023

create a tool to make it very easy to make snapshots of examples #1744

Open

act on some @josharian feedback

d660024

Merge branch 'main' into jmegner-intro

660cc89

jmegner marked this pull request as ready for review August 13, 2023 19:34

pokey reviewed Aug 13, 2023

View reviewed changes

jmegner and others added 6 commits August 13, 2023 19:10

pokey suggestion for move

f3dcc0a

Co-authored-by: Pokey Rule <[email protected]>

pokey suggestion for quick fix

e2d020d

Co-authored-by: Pokey Rule <[email protected]>

pokey suggestion for arg and item

375ea0c

Co-authored-by: Pokey Rule <[email protected]>

[pre-commit.ci lite] apply automatic fixes

f5c562a

pokey suggestion for next example

6b141d5

Co-authored-by: Pokey Rule <[email protected]>

misc pokey suggestions

6b75e22

jmegner added the documentation Improvements or additions to documentation label Aug 21, 2023

Tweaks

d1b2327

pokey reviewed Aug 30, 2023

View reviewed changes

AndreasArvidsson and others added 2 commits September 8, 2023 14:36

Update guide-intermediate.md

5324363

fixed bug

typo fix

808b5b4

jmegner added a commit to jmegner/cursorless-unofficial-doc that referenced this pull request Feb 23, 2024

import with tweaks from cursorless-dev/cursorless#1538

5f65b96

jmegner closed this Jun 20, 2024

		Commands have an action and a target or two. `"chuck air"` has the action `"chuck"` and one target (the `"air"` token).
		`"bring air to bat"` has the action `"bring"` and two targets (the `"air"` and `"bat"` tokens).


		### Targets Can Be Modified

		A target starts as a mark (`"this"`, `"row ten"`, `"green curve air"`, etc) and target modifiers can be applied to suit your needs.

		Special positional target modifiers `"start of"` and `"end of"` do not use delimiters.
		`"bring line to end of row ten"` will bring a copy of the current line content _without line delimiter_ to the end of line 10, meaning line 10 will get content added to it.


		### Targets Sometimes Include Their Delimiter Depending On The Action And Modifiers
		Commands like `"paste"`, `"bring"`, and `"move"` have a target that is a destination.


		This document will try to:

		- Highlight the most useful actions and modifiers in Cursorless so you know which ones to focus on learning first.

		- `"[number] [scope]s"`, like `"chuck three lines row 12"` to delete rows 12-14.
		- `"[number] [scope]s backward"`, like `"chuck three lines backward row 12"` to delete rows 10-12.

intro doc WIP with some concepts and a few example walk throughs #1538

intro doc WIP with some concepts and a few example walk throughs #1538

Conversation

jmegner commented Jun 18, 2023

pokey left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jmegner Jun 19, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pokey Jun 21, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pokey commented Jul 9, 2023

jmegner commented Jul 24, 2023

jmegner commented Aug 7, 2023

jmegner commented Aug 10, 2023

pokey left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jmegner Sep 6, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AndreasArvidsson Aug 14, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jmegner commented Dec 24, 2023

jmegner commented Feb 23, 2024

pokey commented Jun 20, 2024

jmegner commented Jun 20, 2024

jmegner Jun 19, 2023 •

edited

Loading

pokey Jun 21, 2023 •

edited

Loading

jmegner Sep 6, 2023 •

edited

Loading

AndreasArvidsson Aug 14, 2023 •

edited

Loading