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

[jmegner]

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

[pokey]

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

[jmegner]

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]

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]

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

[jmegner]

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]

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

[pokey]

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]

Sounds good to me.