Tutor Blueprint

[joegm]

I think the tutor could do with a little "refactoring". The first half or so is pretty solid but the last 3 chapters especially were just sort of stuck on ad-hoc.

My idea for a general principal is to briefly showcase the fundamentals of each concept (selections,
multiple cursors, etc.), followed by chapters returning to previous the subjects going into more depth on each and building on previous foundations. Essentially akin to a "Spiral Curriculum".

Vimtutor as an example is quite concise, only consisting of 7 chapters with the most core concepts and commands on a broad range. I think this is a good idea, and if we wanted to go further then we could append chapters covering the more advanced commands of previous topics, keeping it digestible while more comprehensive.

Sections Still to Add

• EXTEND/SELECT MODE: v

• FLIP SELECTION: A-;

• FLIP SELECTIONS FORWARD A-:

• CYCLING AND REMOVING SELECTIONS: ) ( A-,

• KEEP/REMOVE SELECTIONS ON REGEX: K A-K

• ALIGN SELECTIONS: &

• SEARCHING FOR SELECTION: *

• ADDING NEXT SELECTION: v-n
  This is more of a technique than a command, but it's still quite distinctive behavior and I didn't know about it until I was told.

• REPEAT SELECTION: A-.

• REPEAT ACTION: .

• REPLACE WITH CHAR: r

• REPLACE WITH REGISTER: R space-R

• INCREMENT/DECREMENT: C-a C-x

• REGISTERS: " <ch>

There are also the "submodes". I think we at least could include goto mode (g), match mode (m) and view mode (z). We could also talk about window mode (space-w) but space mode doesn't feel like it fits in what the tutor primarily covers: direct text editing.

My Proposal

Consider this a WIP, please point out anything you think could be better.

I've laid this out in a sort of git diff style: crossed out means moved elsewhere and bold ++ means new / moved to here. Sections marked with (new) are not currently included. Note that the chapter titles wouldn't be actual sections - just to define the grouping.

This doesn't incorporate the submodes mentioned above, I want to postpone that for now, but it includes all the other "Sections To Add". I'm willing to start work on this but I'd like to hear others' suggestions and ideas first.

The Fundamentals

1. BASIC CURSOR MOVEMENT
2. EXITING HELIX
3. DELETION
4. INSERT MODE
5. MORE ON INSERT MODE
6. SAVING A FILE

++ Alternate Insert Commands.

I wanted to move opening lines earlier, and since it is an insert command, I
extracted the other insert commands out into this mini chapter.

1. ++ MORE ON INSERT MODE
2. ++ OPENING LINES

Motions and Selections

This chapter has gotten longer now, maybe we should postpone some sections until
later? Then again Motions and Selections are pretty central to Helix so perhaps
they deserve a bit more attention.

1. MOTIONS AND SELECTIONS
2. MORE ON MOTIONS
3. THE CHANGE COMMAND
4. COUNTS WITH MOTIONS
5. ++SELECT MODE: v (new)
6. SELECTING LINES
   I also want to add a note for X
7. ++ COLLAPSING SELECTIONS
8. UNDOING

++ Common Editor Actions to Cover Before Multiple Selections.

1. ++ UNDOING
2. ++ COPYING AND PASTING TEXT
3. ++ SEARCHING IN FILE

Multiple Cursors

1. MULTIPLE CURSORS
2. THE SELECT COMMAND
3. SELECTING VIA REGEX
4. COLLAPSING SELECTIONS
5. SELECTING TO A CHARACTER Not related.
6. ++ ALIGN SELECTIONS: & (new) This is helpful to use in the demo for the next section:
7. ++ SPLIT SELECTION ON LINES: A-s (new)

++ More Selection Commands

1. ++SELECTING TO A CHARACTER
2. ++ REPLACE: r (new) Wanted to mix in a miscellaneous command that refers back to the previous section.
3. ++ REPEATING THINGS: . A-. (new)

++ Miscellaneous Text Manipulation

Maybe these should be split up a bit? I like the idea of dropping them in other
chapters like how the change command is in motions & selections, that way you
can immediately use them in tandem with new commands which is more effective
for learning.

2. ++ REPLACE WITH YANKED TEXT: R (new)
3. ++ JOINING LINES
4. ++ INDENTING LINES
5. ++ INCREMENT/DECREMENT: C-a C-x (new)

++ Registers & Macros

1. ++ REGISTERS: " <ch> (new)
2. ++ MACROS

++ More On Searching

1. ++ SEARCHING FOR SELECTION: * (new) Note: mention that searching uses the / register
2. ++ ADDING NEXT INSTANCE OF SELECTION: vn (new)
3. ++ USING THE JUMPLIST

++ Advanced Selection Commands

1. ++CYCLING AND REMOVING SELECTIONS: ) ( A-, (new)
2. ++KEEP/REMOVE SELECTIONS ON REGEX: K A-K (new)
3. ++ CHANGING CASE Mixing in another miscellaneous command for linking in with other sections.
4. ++SPLIT SELECTION ON REGEX: S I have an idea for a demo that includes changing case which is part of the
   reason I moved it here.

Misc

1. COPYING AND PASTING TEXT
2. CHANGING CASE
3. MACROS

Jumplist & Searching

1. USING THE JUMPLIST
2. SEARCHING IN FILE

Line Related Commands

1. JOINING LINES
2. INDENTING LINES
3. OPENING LINES

[David-Else]

You have obviously put a lot of thought into this, thanks for the link to Spiral Curriculum, very interesting!

It all looks good to me. I would add that you could use Vale as a linter for style to ensure consistency, the Microsoft style guide provided is quite good:

https://vale.sh/
https://github.com/errata-ai/vale
https://vale.sh/hub/microsoft/

[joegm]

I'll have to take a minute to learn how to use this, it looks cool! We could even make a style for tutor specific rules like line length, section size, etc but I'll go with the Microsoft one for now.

[David-Else]

Glad you like it, you can omit rules in the config using: https://vale.sh/docs/topics/config/#format-specific-settings

[*.md]
BasedOnStyles = Microsoft

Microsoft.FirstPerson = NO

If you have not tried out https://github.com/valentjn/ltex-ls you are going to love it :) I use them both in Neovim for technical writing using Markdown.

[goyalyashpal]

hey @n0s4 were there PRs etc? (it's unconvenient that github doesn't list the linked/mentioning prs/issues in discussions)

what's the status on this? 😃

as i was also thinking on making some suggestions to tutor, so, it would be good to see where this one stands. thanks :)